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