Skip to content

Commit afc62d7

Browse files
committed
docs: Consolidate extension documentation and fix /spec.trace references
- Remove non-existent /spec.trace from core workflow - Move trace references to /levelup.trace (where it actually exists) - Remove duplicate Architect extension overview from Get Started section - Add missing commands tables for Product and Quick extensions - Replace duplicate Extension Commands section with link to Extensions - Update Core Features table to reflect LevelUp as the knowledge extraction phase
1 parent 2180732 commit afc62d7

1 file changed

Lines changed: 29 additions & 82 deletions

File tree

README.md

Lines changed: 29 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -267,36 +267,9 @@ team-ai-directives/
267267
- `plan.md`: AI refresh section before implementation
268268
- `context-template.md`: Structured placeholders for DISCOVERED_DIRECTIVES/DISCOVERED_SKILLS
269269

270-
### Optional Architecture Support
270+
### Architecture Support
271271

272-
The toolkit includes comprehensive architecture documentation support via the **Architect extension**, which creates and manages Architecture Decision Records (ADRs) and Architecture Descriptions (AD.md) using the Rozanski & Woods methodology.
273-
274-
> **Note**: The Architect extension is bundled and auto-installed during `specify init`.
275-
276-
**Key Features:**
277-
- **Two-level architecture** - System-level ADRs on main branch, feature-level ADRs on feature branches
278-
- **Automatic integration** - Hooks create feature ADRs during `/spec.plan` and validate alignment
279-
- **Greenfield & Brownfield** - `/architect.specify` for new projects, `/architect.init` for existing codebases
280-
281-
**Quick Start:**
282-
283-
```bash
284-
# Greenfield: Create ADRs from PRD
285-
/architect.specify "B2B SaaS platform for real-time supply chain management"
286-
287-
# Brownfield: Reverse-engineer ADRs from code
288-
/architect.init "Django monolith with PostgreSQL, React frontend"
289-
290-
# Generate Architecture Description
291-
/architect.implement
292-
293-
# Validate consistency
294-
/architect.analyze
295-
```
296-
297-
**Commands:** `architect.init`, `architect.specify`, `architect.clarify`, `architect.implement`, `architect.analyze`, `architect.validate`
298-
299-
📖 **Full documentation:** [extensions/architect/README.md](./extensions/architect/README.md)
272+
The toolkit includes architecture documentation support via the **Architect extension** (creates ADRs and Architecture Descriptions). Bundled and auto-installed during `specify init`. See the [Extensions section](#-extensions) for details.
300273

301274
### Framework Options
302275

@@ -386,33 +359,26 @@ Use **`/spec.implement`** to execute all tasks and build your feature according
386359
/spec.implement
387360
```
388361

389-
### 7. Generate session trace (optional)
390-
391-
Use **`/spec.trace`** to generate comprehensive AI session execution traces capturing decisions, patterns, and outcomes.
392-
393-
```bash
394-
/spec.trace
395-
```
396-
397-
**Benefits**: Session traces document AI agent decision-making, execution context, quality gates, and reusable patterns. Stored in `specs/{BRANCH}/trace.md` with your feature artifacts. Optional but enriches `/levelup.specify` CDR extraction when present.
362+
### 7. Level up and contribute knowledge (optional)
398363

399-
### 8. Level up and contribute knowledge
400-
401-
Use the **levelup extension** to extract patterns from your completed feature and contribute reusable knowledge back to your team's shared repository via Context Decision Records (CDRs).
364+
Use the **LevelUp extension** to extract patterns from your completed feature and contribute reusable knowledge back to your team's shared repository via Context Decision Records (CDRs).
402365

403366
```bash
404367
/levelup.specify # Extract CDRs from current feature spec (after /implement)
405-
/levelup.clarify # Resolve ambiguities in discovered CDRs
368+
/levelup.clarify # Resolve ambiguities in discovered CDRs
406369
/levelup.skills python-patterns # Build a skill from accepted CDRs
407-
/levelup.implement # Create PR to team-ai-directives
370+
/levelup.implement # Create PR to team-ai-directives
371+
/levelup.trace # Generate AI session execution traces
408372
```
409373

410374
For brownfield projects, use `/levelup.init` to scan the entire codebase for patterns.
411375

412-
**Commands:** `levelup.init`, `levelup.specify`, `levelup.clarify`, `levelup.skills`, `levelup.implement`, `levelup.trace`
413-
414376
📖 **Full documentation:** [extensions/levelup/README.md](./extensions/levelup/README.md)
415377

378+
### 8. Iterate and improve
379+
380+
Repeat steps 3-7 for each new feature. The cycle of specification → planning → implementation → knowledge extraction continuously improves your team capabilities.
381+
416382
For detailed step-by-step instructions, see our [comprehensive guide](./spec-driven.md).
417383

418384
## 📽️ Video Overview
@@ -446,7 +412,7 @@ The core of Agentic SDLC Spec Kit is a structured workflow that guides AI-assist
446412
| **Technical Planning** | `/spec.plan` | Create technical implementation plans with tech stack & execution modes |
447413
| **Task Breakdown** | `/spec.tasks` | Generate actionable task lists for implementation |
448414
| **Implementation** | `/spec.implement` | Execute all tasks to build the feature with dual execution loops (SYNC/ASYNC) |
449-
| **Session Traces** | `/spec.trace` | Generate AI session execution traces with decisions and patterns |
415+
| **Knowledge Extraction** | `/levelup.*` | Extract patterns and contribute reusable knowledge (LevelUp extension) |
450416

451417
### Team AI Directives Integration
452418

@@ -528,11 +494,26 @@ Test-Driven Development workflow with RED→GREEN→REFACTOR cycles.
528494

529495
Product management workflows for feature prioritization, roadmapping, and release planning.
530496

497+
**Commands:**
498+
| Command | Description |
499+
|---------|-------------|
500+
| `/product.init` | Initialize product management workflow |
501+
| `/product.specify` | Create Product Requirements Document (PRD) |
502+
| `/product.clarify` | Clarify product requirements |
503+
| `/product.implement` | Generate Product Decision Record (PDR) |
504+
| `/product.analyze` | Analyze product decisions consistency |
505+
| `/product.validate` | Validate product alignment |
506+
531507
📖 **Full documentation:** [extensions/product/README.md](./extensions/product/README.md)
532508

533509
### Quick Extension
534510

535-
Quick start templates for rapid project bootstrapping.
511+
One-command, session-based workflow for ad-hoc task execution without file artifacts. Follows 12-factors methodology.
512+
513+
**Commands:**
514+
| Command | Description |
515+
|---------|-------------|
516+
| `/quick.implement` | Execute session-based ad-hoc task (Mission Brief → Context → Plan → Execute) |
536517

537518
📖 **Full documentation:** [extensions/quick/README.md](./extensions/quick/README.md)
538519

@@ -859,7 +840,6 @@ Essential commands for the Spec-Driven Development workflow:
859840
| `/spec.plan` | Create technical implementation plans with your chosen tech stack & SYNC/ASYNC triage |
860841
| `/spec.tasks` | Generate actionable task lists for implementation |
861842
| `/spec.implement` | Execute all tasks to build the feature according to the plan with dual execution loops (SYNC/ASYNC modes) |
862-
| `/spec.trace` | Generate AI session execution traces with decisions, patterns, and evidence (optional, enriches `/levelup.specify`) |
863843

864844
#### Optional Commands
865845

@@ -871,40 +851,7 @@ Additional commands for enhanced quality and validation:
871851
| `/spec.analyze` | Cross-artifact consistency & coverage analysis (run after `/spec.tasks`, before `/spec.implement`) |
872852
| `/spec.checklist` | Generate custom quality checklists that validate requirements completeness, clarity, and consistency (like "unit tests for English") |
873853

874-
#### Extension Commands
875-
876-
Commands provided by bundled extensions. See extension READMEs for full documentation.
877-
878-
**Architect Extension** - [📖 Documentation](./extensions/architect/README.md)
879-
880-
| Command | Description |
881-
|--------------------------|-----------------------------------------------------------------------|
882-
| `/architect.init` | Reverse-engineer architecture from codebase (brownfield) |
883-
| `/architect.specify` | Interactive PRD exploration to create ADRs (greenfield) |
884-
| `/architect.clarify` | Refine ADRs through clarification questions |
885-
| `/architect.implement`| Generate AD.md from ADRs |
886-
| `/architect.analyze` | Validate ADR ↔ AD consistency |
887-
| `/architect.validate` | Validate plan alignment with architecture (READ-ONLY) |
888-
889-
**LevelUp Extension** - [📖 Documentation](./extensions/levelup/README.md)
890-
891-
| Command | Description |
892-
|--------------------------|-----------------------------------------------------------------------|
893-
| `/levelup.init` | Discover CDRs from entire codebase (brownfield analysis) |
894-
| `/levelup.specify` | Extract CDRs from current feature spec context |
895-
| `/levelup.clarify` | Resolve ambiguities in discovered CDRs |
896-
| `/levelup.skills` | Build a single skill from accepted CDRs |
897-
| `/levelup.implement` | Compile accepted CDRs into PR to team-ai-directives |
898-
| `/levelup.trace` | Generate AI session execution traces |
899-
900-
**TDD Extension** - [📖 Documentation](./extensions/tdd/README.md)
901-
902-
| Command | Description |
903-
|--------------------------|-----------------------------------------------------------------------|
904-
| `/tdd.plan` | Planning phase - design before coding |
905-
| `/tdd.tasks` | Detect language/framework + generate hybrid tests |
906-
| `/tdd.implement`| Execute RED→GREEN→REFACTOR |
907-
| `/tdd.validate` | Validate test quality |
854+
All extension commands are documented in the [Extensions section](#-extensions) above.
908855

909856
### Environment Variables
910857

0 commit comments

Comments
 (0)