Generating Technical Spec
Goal
Transform a system architecture document into a detailed technical specification that defines every implementable task, assigns work to the appropriate agent, specifies integration contracts, and establishes a dependency graph so that work can proceed in parallel where possible.
When to Use
- An architecture document exists and implementation is about to begin
- You need to coordinate work across multiple agents or team members
- A large feature requires decomposition into smaller, trackable units
- You need to estimate effort and identify the critical path for delivery
Instructions
1. Review the Architecture Document
Read the architecture produced by the designing-architecture skill. Identify:
- Every component and its responsibility
- All API contracts and integration points
- The data model and storage decisions
- Authentication and authorization boundaries
2. Decompose into Work Packages
Break each component into atomic tasks. A good task:
- Can be completed in a single working session
- Has a clear definition of done
- Produces a testable artifact (code, config, migration, test suite)
Group tasks by component, then order them by dependency.
3. Assign Tasks to Agents
Map each task to the agent best suited to implement it based on domain:
- Frontend Agent -- UI components, client state, routing
- Backend Agent -- API endpoints, business logic, middleware
- Database Agent -- Schema design, migrations, seed data
- DevOps Agent -- CI/CD, infrastructure, deployment config
- Testing Agent -- Test plans, integration tests, e2e tests
4. Define Integration Points
For every boundary where two components interact, define:
- The contract (API schema, event format, shared type)
- Which task produces the contract and which tasks consume it
- How to verify the integration (contract tests, integration tests)
5. Set Dependencies and Estimate Difficulty
Build a dependency graph:
- Tasks that can run in parallel should have no dependency link
- Tasks that block other tasks must be completed first
- Estimate each task as Low, Medium, or High difficulty
Example -- turning a web app architecture into tasks:
| Task ID |
Description |
Agent |
Difficulty |
Dependencies |
| T-001 |
Define database schema |
Database |
Medium |
None |
| T-002 |
Create migration scripts |
Database |
Low |
T-001 |
| T-003 |
Implement user registration endpoint |
Backend |
Medium |
T-001 |
| T-004 |
Implement login endpoint with JWT |
Backend |
Medium |
T-001 |
| T-005 |
Add auth middleware |
Backend |
Low |
T-004 |
| T-006 |
Implement profile CRUD endpoints |
Backend |
Medium |
T-005 |
| T-007 |
Build registration form component |
Frontend |
Medium |
T-003 |
| T-008 |
Build login form component |
Frontend |
Medium |
T-004 |
| T-009 |
Build profile page |
Frontend |
Medium |
T-006 |
| T-010 |
Set up CI pipeline |
DevOps |
Medium |
None |
| T-011 |
Write auth integration tests |
Testing |
Medium |
T-003, T-004 |
| T-012 |
Write e2e test for registration flow |
Testing |
High |
T-007, T-008 |
| T-013 |
Add rate limiting middleware |
Backend |
Low |
T-005 |
| T-014 |
Seed database with test data |
Database |
Low |
T-002 |
| T-015 |
Configure production deployment |
DevOps |
High |
T-010 |
6. Identify the Critical Path
Trace the longest chain of dependent tasks from start to finish. This is the critical path -- any delay on these tasks delays the entire project.
7. Produce the Technical Spec
Compile everything into a document following references/spec-template.md. The spec should be the single source of truth for what gets built, by whom, and in what order.
Constraints
✅ Do
- Make every task atomic and completable in a single session
- Define clear inputs and outputs for each task
- Set realistic dependencies -- do not over-serialize independent work
- Include integration tasks explicitly (they are often forgotten)
- Include testing tasks for every component and integration point
- Specify the contract format for each integration boundary
- Identify the critical path and flag it clearly
❌ Don't
- Create tasks too large or vague to complete in one session
- Skip integration tasks between components
- Forget testing tasks (unit, integration, e2e)
- Assign all tasks to a single agent when work can be parallelized
- Create circular dependencies in the task graph
- Leave difficulty estimates out -- they are needed for planning
- Assume agents share implicit context; make everything explicit in the spec
Output Format
A Markdown document following the structure defined in references/spec-template.md.
Key sections:
- System Overview (architecture summary)
- Component Specifications
- API Contracts
- Data Model
- Task Breakdown (table with ID, description, agent, difficulty, dependencies)
- Integration Points
- Testing Strategy
Dependencies
../designing-architecture/SKILL.md -- provides the architecture document as input../../shared/task-tracking/SKILL.md -- for tracking task progress during implementationreferences/spec-template.md -- structural template for the output document
1---2name: generating-technical-spec3description: Break a system architecture into implementable work packages with clear tasks, dependencies, and integration contracts.4---56# Generating Technical Spec78## Goal910Transform a system architecture document into a detailed technical specification that defines every implementable task, assigns work to the appropriate agent, specifies integration contracts, and establishes a dependency graph so that work can proceed in parallel where possible.1112## When to Use1314- An architecture document exists and implementation is about to begin15- You need to coordinate work across multiple agents or team members16- A large feature requires decomposition into smaller, trackable units17- You need to estimate effort and identify the critical path for delivery1819## Instructions2021### 1. Review the Architecture Document2223Read the architecture produced by the `designing-architecture` skill. Identify:24- Every component and its responsibility25- All API contracts and integration points26- The data model and storage decisions27- Authentication and authorization boundaries2829### 2. Decompose into Work Packages3031Break each component into atomic tasks. A good task:32- Can be completed in a single working session33- Has a clear definition of done34- Produces a testable artifact (code, config, migration, test suite)3536Group tasks by component, then order them by dependency.3738### 3. Assign Tasks to Agents3940Map each task to the agent best suited to implement it based on domain:41- **Frontend Agent** -- UI components, client state, routing42- **Backend Agent** -- API endpoints, business logic, middleware43- **Database Agent** -- Schema design, migrations, seed data44- **DevOps Agent** -- CI/CD, infrastructure, deployment config45- **Testing Agent** -- Test plans, integration tests, e2e tests4647### 4. Define Integration Points4849For every boundary where two components interact, define:50- The contract (API schema, event format, shared type)51- Which task produces the contract and which tasks consume it52- How to verify the integration (contract tests, integration tests)5354### 5. Set Dependencies and Estimate Difficulty5556Build a dependency graph:57- Tasks that can run in parallel should have no dependency link58- Tasks that block other tasks must be completed first59- Estimate each task as Low, Medium, or High difficulty6061**Example** -- turning a web app architecture into tasks:6263| Task ID | Description | Agent | Difficulty | Dependencies |64|---------|---------------------------------------|----------|------------|--------------|65| T-001 | Define database schema | Database | Medium | None |66| T-002 | Create migration scripts | Database | Low | T-001 |67| T-003 | Implement user registration endpoint | Backend | Medium | T-001 |68| T-004 | Implement login endpoint with JWT | Backend | Medium | T-001 |69| T-005 | Add auth middleware | Backend | Low | T-004 |70| T-006 | Implement profile CRUD endpoints | Backend | Medium | T-005 |71| T-007 | Build registration form component | Frontend | Medium | T-003 |72| T-008 | Build login form component | Frontend | Medium | T-004 |73| T-009 | Build profile page | Frontend | Medium | T-006 |74| T-010 | Set up CI pipeline | DevOps | Medium | None |75| T-011 | Write auth integration tests | Testing | Medium | T-003, T-004 |76| T-012 | Write e2e test for registration flow | Testing | High | T-007, T-008 |77| T-013 | Add rate limiting middleware | Backend | Low | T-005 |78| T-014 | Seed database with test data | Database | Low | T-002 |79| T-015 | Configure production deployment | DevOps | High | T-010 |8081### 6. Identify the Critical Path8283Trace the longest chain of dependent tasks from start to finish. This is the critical path -- any delay on these tasks delays the entire project.8485### 7. Produce the Technical Spec8687Compile everything into a document following `references/spec-template.md`. The spec should be the single source of truth for what gets built, by whom, and in what order.8889## Constraints9091### ✅ Do92- Make every task atomic and completable in a single session93- Define clear inputs and outputs for each task94- Set realistic dependencies -- do not over-serialize independent work95- Include integration tasks explicitly (they are often forgotten)96- Include testing tasks for every component and integration point97- Specify the contract format for each integration boundary98- Identify the critical path and flag it clearly99100101### ❌ Don't102- Create tasks too large or vague to complete in one session103- Skip integration tasks between components104- Forget testing tasks (unit, integration, e2e)105- Assign all tasks to a single agent when work can be parallelized106- Create circular dependencies in the task graph107- Leave difficulty estimates out -- they are needed for planning108- Assume agents share implicit context; make everything explicit in the spec109110111## Output Format112113A Markdown document following the structure defined in `references/spec-template.md`.114115Key sections:1161. System Overview (architecture summary)1172. Component Specifications1183. API Contracts1194. Data Model1205. Task Breakdown (table with ID, description, agent, difficulty, dependencies)1216. Integration Points1227. Testing Strategy123124## Dependencies125126- `../designing-architecture/SKILL.md` -- provides the architecture document as input127- `../../shared/task-tracking/SKILL.md` -- for tracking task progress during implementation128- `references/spec-template.md` -- structural template for the output document
7a336e6e