skills/docs/worklogs/2026-01-18-intent-approach-work-framework-design.md

title	date	keywords	commits	compression_status
Intent/Approach/Work Framework Design	2026-01-18	spec-driven-development planning-framework intent-approach-work beads terminology research	14	uncompressed

Session Summary

Date: 2026-01-18 Focus Area: Designing a lightweight spec-driven planning framework for AI coding workflows

Accomplishments

• Researched existing spec-driven development tools (GitHub Spec-Kit, Amazon Kiro, Tessl, AGENTS.md)
• Researched traditional software engineering terminology (RFCs, ADRs, SRS, user stories)
• Created epic for spec-driven planning framework (skills-oh8m)
• Iterated from complex 9-task structure down to simple 3-task structure
• Synthesized terminology: Intent / Approach / Work (avoiding overloaded terms)
• Defined full and minimal templates for structured beads
• Closed duplicate issue (skills-0y9) that covered same ground
• 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
• GitHub Spec-Kit Repository
• Amazon Kiro Documentation
• AGENTS.md Standard
• Addy Osmani: My LLM Coding Workflow

Secondary sources:

• Thoughtworks: Spec-Driven Development
• Pragmatic Engineer: RFCs and Design Docs
• JetBrains: Spec-Driven Approach for AI Coding
• GitHub ADR Repository

Architecture Notes

The framework follows a simple pattern:

Intent   →   Approach   →   Work
(what)       (how)          (do)

Full template (for significant work):

## 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):

## 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 - earlier architecture work
• 2026-01-11 HQ Architecture - 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