worklog: Intent/Approach/Work framework design session
This commit is contained in:
dan
parent
ade42fb99d
commit
fd5e164f6c
|
|
@ -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
|
||||||
Loading…
Reference in a new issue