---
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