Skip to content

docs: update CSW spec documentation and cleanup Phase 3 #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mikestankavich merged 1 commit into from
Oct 26, 2025
Merged

docs: update CSW spec documentation and cleanup Phase 3 #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 6 additions & 37 deletions spec/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,29 +5,25 @@ This system combines the best practices from Context Engineering (Cole Medin), 3
## Quick Start

1. **Create a specification**

```bash
mkdir -p spec/my-feature
cp spec/template.md spec/my-feature/spec.md
# Edit spec.md with your requirements
```

2. **Generate implementation plan**

```
/plan my-feature
# or just: /plan (auto-detects if only one spec)
```

3. **Build the feature**

```
/build
# Auto-detects the spec with plan.md
```

4. **Validate readiness**

```
/check
```
Expand Down Expand Up @@ -80,45 +76,37 @@ This system is built on three core principles:
## Workflow Overview

### 1. Specification (Human writes)

Define WHAT needs to be built, not HOW. Include:

- Clear outcome and success criteria
- Examples and references
- Constraints and context

### 2. Planning (AI generates)

AI analyzes the spec and creates detailed implementation plan:

- Task breakdown
- Risk assessment
- Validation steps

### 3. Building (AI executes)

AI implements based on plan with:

- Continuous validation
- Progress tracking
- Error recovery

### 4. Shipping (AI completes)

Final validation and PR preparation:

- Comprehensive checks
- Documentation updates
- Clean git history

## Command Reference

| Command | Purpose | Notes |
| -------- | -------------------------------- | ----------------------------------------- |
| `/plan` | Generate implementation plan | Auto-detects spec or accepts fragment |
| `/build` | Execute implementation | Validates continuously; full suite at end |
| `/check` | Validate PR readiness (optional) | /ship runs this automatically |
| `/ship` | Complete and ship | Creates PR; runs /check first |
| Command | Purpose | Notes |
|---------|---------|-------|
| `/plan` | Generate implementation plan | Auto-detects spec or accepts fragment |
| `/build` | Execute implementation | Validates continuously; full suite at end |
| `/check` | Validate PR readiness (optional) | /ship runs this automatically |
| `/ship` | Complete and ship | Creates PR; runs /check first |

## Feature Lifecycle & Cleanup Workflow

Expand All @@ -127,29 +115,25 @@ Final validation and PR preparation:
CSW uses **rebase workflow** (linear history), not merge commits.

**When you run `/ship`**:

1. Creates PR from feature branch
2. Commits and pushes to remote
3. PR is ready for review and merge

**When you run `/cleanup` (after PR is merged)**:

1. Syncs with main branch
2. Deletes merged feature branches
3. Creates `cleanup/merged` staging branch
4. **DELETES** spec directories that have `log.md` (proof of completion)
5. Commits the cleanup

**When you run `/plan` (next feature)**:

1. Detects `cleanup/merged` branch and renames it to new feature name
2. Or creates new feature branch from main
3. Ready to start next feature

### Cleanup = DELETE

The `/cleanup` command deletes shipped specs from your working tree:

1. Finds all spec directories with `log.md` files
2. **DELETES** those spec directories (`spec/feature-name/`)
3. Commits the deletion on `cleanup/merged` branch
Expand Down Expand Up @@ -184,7 +168,6 @@ sequenceDiagram
### Path Simplification

Paths simplified from `spec/active/feature/` to `spec/feature/`:

- Old: `spec/active/authentication/spec.md`
- New: `spec/authentication/spec.md`

Expand All @@ -193,13 +176,11 @@ Paths simplified from `spec/active/feature/` to `spec/feature/`:
### Arbitrary Nesting

After `spec/`, organize however you want:

- **Flat**: `spec/auth/`, `spec/dashboard/`
- **By layer**: `spec/frontend/auth/`, `spec/backend/users/`
- **By team**: `spec/team-a/feature-x/`, `spec/team-b/feature-y/`

**Feature identity** = full relative path under spec/:

- `spec/auth/` → feature: `"auth"`
- `spec/frontend/auth/` → feature: `"frontend/auth"`
- `spec/team-a/feature-x/` → feature: `"team-a/feature-x"`
Expand All @@ -209,33 +190,28 @@ After `spec/`, organize however you want:
Commands accept fragments, not full paths:

**Zero arguments** (auto-detect):

```bash
/plan # Auto-detects if only 1 spec exists
/build # Auto-detects if only 1 plan exists
```

**Fragment matching** (Claude fuzzy matches):

```bash
/plan auth # Matches spec/auth/ or spec/frontend/auth/
/plan frontend # Matches spec/frontend/auth/
/plan authentication # Typo-tolerant, matches "auth"
```

**How it works** (separation of concerns):

1. **Bash layer**: Runs `find spec/ -name "spec.md"`, returns ALL matches
2. **Claude layer**: Fuzzy matches your fragment, handles disambiguation

**Command-specific filtering**:

- `/plan` → Looks for `spec.md` files (specs ready to plan)
- `/build` → Looks for `plan.md` files (specs ready to build)
- `/ship` → Looks for `plan.md` files (specs ready to ship)

**Interactive disambiguation**: Multiple matches show numbered list:

```
I found 2 specs matching "auth":
1. frontend/auth
Expand All @@ -248,7 +224,6 @@ You can respond with: `1`, `frontend`, or `the frontend one`.
### Zero-Arg Sequential Workflow

Solo development with single feature needs zero path arguments:

```bash
/spec my-feature # Create spec/my-feature/
/plan # Auto-detect (only 1 spec)
Expand All @@ -261,15 +236,13 @@ Solo development with single feature needs zero path arguments:
## Best Practices

### DO:

- ✅ Write clear, specific requirements
- ✅ Include examples from the codebase
- ✅ Reference documentation
- ✅ Define validation criteria
- ✅ Use semantic commit messages

### DON'T:

- ❌ Mix multiple features in one spec
- ❌ Skip validation steps
- ❌ Ignore failing tests
Expand All @@ -279,7 +252,6 @@ Solo development with single feature needs zero path arguments:
## Validation Standards

All features must pass validation commands defined in `spec/stack.md`:

- **Lint** - No linting errors
- **Typecheck** - No type errors (if applicable to your stack)
- **Test** - All tests passing
Expand All @@ -298,19 +270,16 @@ The specific commands depend on your tech stack. See `spec/stack.md` for your pr
## Troubleshooting

**Build fails validation?**

- Check log.md for specific errors
- Fix the code, not the tests
- Re-run validation

**Can't ship?**

- Run `/check` for detailed report
- Fix all critical issues
- Try again

**Lost context?**

- Check log.md for progress
- Plan.md has the full strategy
- Resume from last completed task
Loading