Manage multi-phase development workflows with specifications, planning, execution, and handoff documentation. Ideal for complex features, refactoring, or structured development cycles.
A comprehensive workflow system for managing complex development tasks through structured sessions with specifications, planning, phased execution, and context preservation.
This skill provides a complete framework for "dev sessions" - structured development cycles that break complex work into manageable phases. Each session creates a documented workspace with specifications, implementation plans, phase-by-phase execution, and comprehensive handoff documentation.
Sessions create a directory at `docs/dev-sessions/$(date +"%Y-%m-%d-%H%M")-{slug}` containing:
When the user invokes this skill to start a new dev session:
1. Ask the user for a slug/name for this session (short, kebab-case identifier)
2. Create session directory: `docs/dev-sessions/$(date +"%Y-%m-%d-%H%M")-{slug}`
3. If resuming, read existing `spec.md`, `plan.md`, and any `phaseN-context.md` files
4. Inform the user that the session is initialized and ready for brainstorming
When developing specifications:
1. Read any existing `spec.md` in the session directory
2. Engage in interactive questioning to understand:
- Core behavioral requirements
- Edge cases and error conditions
- Testing approach and validation criteria
- User experience considerations
- Performance or scalability requirements
3. Focus on **what** the system should do, not **how** to implement it
4. Iterate until the user confirms the spec is complete
5. Write the final specification to `spec.md` in the session directory
6. **Format:** Use clear markdown with sections for Requirements, Behavior, Edge Cases, Testing Strategy
When creating the implementation plan:
1. Read `spec.md` for complete context
2. Generate a hierarchical markdown outline organized into phases and steps
3. **Phase sizing:** Each phase should fit comfortably in a single Claude Code session (equivalent to 3-6 hours of focused work)
4. **Linear progression:** Phases build on each other, each concluding in a clean, validated state
5. **Testing integration:** Include testing in each phase, not deferred to the end
6. **Format:**
```markdown
# Implementation Plan
## Phase 1: [Phase Name]
- Step 1.1: [Specific task]
- Step 1.2: [Specific task]
- Testing: [What to test and validate]
## Phase 2: [Phase Name]
...
```
7. Save the plan to `plan.md` in the session directory
When executing the first phase:
1. Read BOTH `spec.md` and `plan.md` for full context
2. Implement all steps in Phase 1 according to the plan
3. **Critical testing rules:**
- NEVER delete or disable tests except when removing code or refactoring for better coverage
- ALL tests must pass before phase completion
- NO tweaking assertions to match observed results
- NO mocks (prefer integration tests to avoid LLM hallucination risks)
4. Run all tests and ensure they pass
5. Create `phase1-context.md` containing:
- What was implemented
- Key decisions made
- Problems encountered and solutions
- Current state of the codebase
- What the next session needs to know
6. Commit changes locally with descriptive commit message
7. **NEVER push automatically** - only commit locally unless explicitly instructed
When continuing to subsequent phases:
1. Read `spec.md`, `plan.md`, and ALL previous `phaseN-context.md` files
2. Implement the next phase following the same testing rules as Phase 4
3. Create `phaseN-context.md` for the current phase
4. Commit changes locally
5. Repeat for each remaining phase
When the user requests to finalize the session:
1. Create `recap.md` combining all phase contexts into a comprehensive summary
2. Generate a humble, accurate pull request description in `pr.md` that:
- Describes what was changed and why
- Links to the spec and plan documents
- Highlights testing coverage
- Notes any trade-offs or future considerations
3. Commit the final documentation with message like "docs: finalize dev session [slug]"
4. Inform the user that the session is complete and ready for PR creation
```
User: Start a new dev session for adding user authentication
Assistant: [Creates session directory, asks clarifying questions]
User: Let's brainstorm the spec
Assistant: [Interactive questioning, writes spec.md]
User: Create the implementation plan
Assistant: [Reads spec.md, generates plan.md with phases]
User: Execute phase 1
Assistant: [Implements, tests, creates phase1-context.md, commits]
User: Continue to phase 2
Assistant: [Reads all context, implements phase 2, creates phase2-context.md, commits]
User: Finalize the session
Assistant: [Creates recap.md and pr.md, commits documentation]
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/structured-dev-sessions/raw