workflow
Standard workflow for implementing features with specs and planning documents. Use when starting a new feature, planning implementation, or working on any non-trivial task.
When & Why to Use This Skill
This Claude skill implements a rigorous, documentation-first workflow for software engineering. It streamlines the transition from concept to code by enforcing a structured process of codebase analysis, technical specification drafting, and incremental implementation. By prioritizing simplicity and mandatory plan verification, it ensures that complex features are executed with high precision and maintainable architecture.
Use Cases
- New Feature Development: Systematically planning and executing complex features by creating timestamped specifications and actionable todo lists before any code is written.
- Architectural Decision Tracking: Utilizing the dedicated /specs/ directory to document cross-cutting concerns and major design choices for long-term project transparency.
- Risk-Mitigated Refactoring: Breaking down large-scale code changes into small, simple, and verifiable steps to prevent regressions and maintain codebase integrity.
- Collaborative Implementation: Enhancing human-AI alignment through a mandatory 'check-in' phase where the user reviews and approves the technical plan before execution begins.
| name | workflow |
|---|---|
| description | Standard workflow for implementing features with specs and planning documents. Use when starting a new feature, planning implementation, or working on any non-trivial task. |
Standard Workflow
- First think through the problem, read the codebase for relevant files, and write a plan to specs/[timestamp] [feature-name].md where [timestamp] is the timestamp in YYYYMMDDThhmmss format and [feature-name] is the name of the feature.
- The plan should have a list of todo items that you can check off as you complete them
- Before you begin working, check in with me and I will verify the plan.
- Then, begin working on the todo items, marking them as complete as you go.
- Please every step of the way just give me a high level explanation of what changes you made
- Make every task and code change you do as simple as possible. We want to avoid making any massive or complex changes. Every change should impact as little code as possible. Everything is about simplicity.
- Finally, add a review section to the .md file with a summary of the changes you made and any other relevant information.
Spec Placement
Specs always live at the root level of their scope (not inside docs/):
/specs/- Cross-cutting features, architecture decisions, general tooling/apps/[app]/specs/- Features specific to one app only/packages/[pkg]/specs/- Package-specific implementation details
When in doubt, use /specs/. Move to app/package-specific only if the spec truly belongs there.