diff --git a/docs/worklogs/2026-01-18-intent-approach-work-framework-design.md b/docs/worklogs/2026-01-18-intent-approach-work-framework-design.md new file mode 100644 index 0000000..26eae17 --- /dev/null +++ b/docs/worklogs/2026-01-18-intent-approach-work-framework-design.md @@ -0,0 +1,219 @@ +--- +title: "Intent/Approach/Work Framework Design" +date: 2026-01-18 +keywords: [spec-driven-development, planning-framework, intent-approach-work, beads, terminology, research] +commits: 14 +compression_status: uncompressed +--- + +# Session Summary + +**Date:** 2026-01-18 +**Focus Area:** Designing a lightweight spec-driven planning framework for AI coding workflows + +# Accomplishments + +- [x] Researched existing spec-driven development tools (GitHub Spec-Kit, Amazon Kiro, Tessl, AGENTS.md) +- [x] Researched traditional software engineering terminology (RFCs, ADRs, SRS, user stories) +- [x] Created epic for spec-driven planning framework (skills-oh8m) +- [x] Iterated from complex 9-task structure down to simple 3-task structure +- [x] Synthesized terminology: Intent / Approach / Work (avoiding overloaded terms) +- [x] Defined full and minimal templates for structured beads +- [x] Closed duplicate issue (skills-0y9) that covered same ground +- [x] Documented all research sources in epic for future reference + +# Key Decisions + +## Decision 1: Structure lives in bead issues, not separate files + +- **Context:** Spec-Kit and Kiro use separate spec files (.specs/, requirements.md, design.md, tasks.md) +- **Options considered:** + 1. Separate .specs/ directory with markdown files (like Spec-Kit) + 2. Conversation flow only (AI phases through design→plan→tasks) + 3. Structure in bead issue bodies with ## sections + 4. Hybrid approach +- **Rationale:** Beads already track work. Adding structure to bead bodies avoids tool proliferation while getting the benefits of phased planning. +- **Impact:** Much simpler implementation - just conventions, no new CLI commands or file formats + +## Decision 2: Use "Intent / Approach / Work" terminology + +- **Context:** Industry terminology is fragmented: + - Spec-Kit: Specify → Plan → Tasks + - Kiro: Requirements → Design → Tasks + - Traditional: Requirements → Design → Implementation +- **Options considered:** + 1. Use Spec-Kit terms (Specify/Plan/Tasks) + 2. Use Kiro terms (Requirements/Design/Tasks) + 3. Synthesize new unambiguous terms +- **Rationale:** "Design" is overloaded (visual vs technical), "Plan" vs "Design" unclear, "Spec" vs "Requirements" is style. Created new terms that map cleanly to the underlying concepts. +- **Impact:** Clear terminology that doesn't carry baggage from other frameworks + +## Decision 3: Keep "Work" despite slight awkwardness + +- **Context:** "Work" as a noun for the tasks section felt slightly unusual +- **Options considered:** + 1. Tasks (industry standard but overloaded) + 2. Steps (clear but implies linear) + 3. Checklist (format not content) + 4. Work (the actual concept) +- **Rationale:** "Work" directly describes the concept - concrete work to be done. The slight awkwardness is worth the clarity. +- **Impact:** Consistent terminology across all documentation + +# Problems & Solutions + +| Problem | Solution | Learning | +|---------|----------|----------| +| Initial design too complex (9 tasks, CLI commands, file format) | User feedback: "kinda what I like is a three phase design/plan/tasks for smaller things" | Start simple, add complexity only when needed | +| Terminology divergence across sources | Deep research + synthesis into new terms | When standards conflict, synthesize rather than pick sides | +| Duplicate issue (skills-0y9) existed from earlier work | Closed as superseded by new epic | Check for existing work before creating new issues | + +# Technical Details + +## Code Changes + +- Total files modified: 0 (this was design/research work) +- Key beads created/updated: + - `skills-oh8m` - Epic: Spec-driven planning framework + - `skills-ankb` - Define Intent/Approach/Work workflow + - `skills-4ecn` - Define structured bead template + - `skills-5xkg` - Document workflow +- Beads closed: + - `skills-npwv` - Original research issue (completed) + - `skills-0y9` - Duplicate from earlier work + - `skills-ya44`, `skills-rqi3`, `skills-eg87`, `skills-sx8u`, `skills-2cyj`, `skills-nscx` - Obsolete tasks from complex design + +## Research Sources Consulted + +Primary sources: +- [Martin Fowler: Understanding Spec-Driven Development - 3 Tools](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html) +- [GitHub Spec-Kit Repository](https://github.com/github/spec-kit) +- [Amazon Kiro Documentation](https://kiro.dev/) +- [AGENTS.md Standard](https://agents.md) +- [Addy Osmani: My LLM Coding Workflow](https://addyosmani.com/blog/ai-coding-workflow/) + +Secondary sources: +- [Thoughtworks: Spec-Driven Development](https://www.thoughtworks.com/en-us/insights/blog/agile-engineering-practices/spec-driven-development-unpacking-2025-new-engineering-practices) +- [Pragmatic Engineer: RFCs and Design Docs](https://newsletter.pragmaticengineer.com/p/rfcs-and-design-docs) +- [JetBrains: Spec-Driven Approach for AI Coding](https://blog.jetbrains.com/junie/2025/10/how-to-use-a-spec-driven-approach-for-coding-with-ai/) +- [GitHub ADR Repository](https://github.com/joelparkerhenderson/architecture-decision-record) + +## Architecture Notes + +The framework follows a simple pattern: + +``` +Intent → Approach → Work +(what) (how) (do) +``` + +**Full template** (for significant work): +```markdown +## Intent +**Problem**: What's broken or missing +**Solution**: High-level approach (not technical) +**Constraints**: Requirements, limits, must-haves + +## Approach +Technical approach, key decisions, trade-offs + +Files: +- path/to/file.ts (change description) + +## Work +- [ ] Step 1 +- [ ] Step 2 +``` + +**Minimal template** (for smaller things): +```markdown +## Intent +One-liner: what and why + +## Work +- [ ] Step 1 +- [ ] Step 2 +``` + +# Process and Workflow + +## What Worked Well + +- Starting with broad research before designing +- User feedback driving simplification ("let's make it simpler") +- Iterating on terminology with explicit comparison tables +- Using beads to track the design work itself + +## What Was Challenging + +- Navigating divergent industry terminology +- Resisting urge to add complexity (CLI commands, file formats) +- Finding the right level of abstraction for terminology + +# Learning and Insights + +## Technical Insights + +- Spec-driven development is a major 2025 trend, emerging as counter to "vibe coding" +- Key tools (Spec-Kit, Kiro, Tessl) all converge on similar phases but use different terms +- AGENTS.md has become a de facto standard (60k+ projects, Linux Foundation stewardship) +- The pattern Intent→Approach→Work maps cleanly to all existing frameworks + +## Process Insights + +- Terminology matters - overloaded terms create confusion +- Simpler is usually better - structured bead bodies vs separate files +- Research before design prevents reinventing wheels + +## Architectural Insights + +- Planning artifacts (specs) and tracking artifacts (beads) can be combined +- Human checkpoints between phases are the key value, not the file format +- The workflow is more important than the tooling + +# Context for Future Work + +## Open Questions + +- When is Approach section needed vs optional? +- How detailed should Intent be for small tasks? +- How to handle work items that grow into their own beads? + +## Next Steps + +- Define Intent/Approach/Work workflow in detail (skills-ankb) +- Create structured bead template with examples (skills-4ecn) +- Write user documentation (skills-5xkg) + +## Related Work + +- [2026-01-10 Multi-Agent Lego Architecture Design](2026-01-10-multi-agent-lego-architecture-design.org) - earlier architecture work +- [2026-01-11 HQ Architecture](2026-01-11-hq-architecture-orch-consensus-beads-cleanup.org) - beads workflow context +- skills-vz05 - Agent Coordination epic (blocked by skills-0y9, now closed) + +# Raw Notes + +Key industry stats from research: +- GitHub Spec-Kit: 40k+ stars since Aug 2025 launch +- AGENTS.md: 60k+ OSS projects, Linux Foundation stewardship +- 41% of code is AI-generated/assisted in 2025 (Stack Overflow survey) +- 65% of developers use AI coding tools weekly + +Terminology mapping table that drove the synthesis: + +| Tool | Phase 1 | Phase 2 | Phase 3 | Phase 4 | +|------|---------|---------|---------|---------| +| Spec-Kit | Specify | Plan | Tasks | Implement | +| Kiro | Requirements | Design | Tasks | (execute) | +| Tessl | Spec | (inline) | (inline) | Generate | +| SDLC | Requirements | Design | Implementation | Testing | +| **Ours** | **Intent** | **Approach** | **Work** | (execute) | + +The Martin Fowler article was particularly valuable for comparing Kiro vs Spec-Kit vs Tessl side-by-side. + +# Session Metrics + +- Commits made: 14 (mostly bd sync/daemon export) +- Files touched: 0 (design/research session) +- Beads created: 10 +- Beads closed: 8 (1 complete, 7 obsolete from simplification) +- Beads remaining: 3 open tasks + 1 epic