agent-skills / feature-workflow
AGENTS.md2 starsChanged 3 days agoMITView on GitHub
Version: 1.0.0 Author: arraydude Note: This document is optimized for AI agent consumption. For quick reference, see SKILL.md. This guide covers the complete workflow for planning, specifying, implementing, and archiving features. It codifies a battle-tested process derived from 18+ completed feature specs, covering spec creation, phased implementation, progress tracking, PR strategy, and archival. Contains 19 rules across 6 categories. Impact: CRITICAL Every spec document follows a consistent structure with these required elements in order:
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository11 other files it gives its agents.
- skills/react-query-best-practices/AGENTS.mdAGENTS.md
- smc-crt-analysisAGENTS.md
- skills/validate-pr/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- babysit-prSkill
- feature-workflowSkill
- qa-verifySkill
- react-query-best-practicesSkill
- react-query-migrate-v5Skill
- smc-crt-analysisSkill
- validate-prSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
26 rules. About 0 are common, 22 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈22
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 51
Every spec document follows a consistent structure with these required elements in order:
- Distinctive: line 120
Before/after comparison table
- Distinctive: line 135
Before/after metric targets
- Distinctive: line 143
Before proposing any changes, thoroughly document what exists today.
- Distinctive: line 148
Document current behavior with code snippets
- Distinctive: line 192
After each phase completes: add completion report section
- Distinctive: line 193
When problems are discovered: add to blockers/issues section
- Distinctive: line 194
When decisions change: update architecture section with date and rationale
- Distinctive: line 195
When metrics are measured: update metrics table with actual values
- Distinctive: line 217
Never delete history -- mark old plans as superseded, not removed.
- Distinctive: line 318
Never delete old code in the same phase as creating new code
- Distinctive: line 358
When a phase completes, add a completion report:
- Distinctive: line 389
Every spec should include a metrics table.
- Very specific: line 410
Every PR opened from a feature/* branch must target develop.
- Distinctive: line 508
Never mix unrelated changes
- Distinctive: line 521
All phases marked as completed
- Distinctive: line 524
No remaining TODOs or blockers
- Very specific: line 528
File naming: Keep UPPERCASE_NAME_SPEC.md.
- Distinctive: line 540
Before archiving, ensure the spec captures:
- Distinctive: line 628
Mid-phase discovery: Add to blockers section, update plan
- Distinctive: line 629
Scope change: Update Goals, add/remove phases, update metrics
- Distinctive: line 630
Architecture pivot: Document rejection and new approach with rationale
- Very specific: line 633
Always update Last Updated: date
- Distinctive: line 634
Add dated entry to "Recent Updates" (newest first)
- Distinctive: line 635
Update future phase descriptions if affected
- Very specific: line 636
Never delete history -- use ~~strikethrough~~ for superseded content
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Feature Workflow Guide - Complete Reference
Version: 1.0.0
Author: arraydude
Note: This document is optimized for AI agent consumption. For quick reference, see SKILL.md.
Abstract
This guide covers the complete workflow for planning, specifying, implementing, and archiving features. It codifies a battle-tested process derived from 18+ completed feature specs, covering spec creation, phased implementation, progress tracking, PR strategy, and archival. Contains 19 rules across 6 categories.
Table of Contents
- Spec Structure & Content -- CRITICAL
- 1.1 Required Spec Document Structure
- 1.2 Required Content for Each Spec Section
- 1.3 Always Start With Current State Analysis
- 1.4 Spec as a Living Document
- Phase Design -- CRITICAL
- 2.1 Phase 0 is Always Foundation Work
- 2.2 How to Decompose Work Into Phases
- 2.3 Order Phases by Dependency Chain
- Progress Tracking -- HIGH
- 3.1 Use Consistent Status Indicators
- 3.2 Write Completion Reports Per Phase
- 3.3 Include Before/After Metrics Tables
- PR Strategy -- HIGH
- 4.0 Feature PRs Always Target develop, Never main -- CRITICAL
- 4.1 One PR Per Phase for Reviewability
- 4.2 Branch Naming Follows GitFlow Conventions
- 4.3 Keep PRs Focused With Clear Scope Documentation
- Archival -- MEDIUM
- 5.1 When and How to Archive Completed Specs
- 5.2 Preserve Completion Notes and Learnings
- Workflow Collaboration -- MEDIUM
- 6.1 Iterative Planning Between AI and Developer
- 6.2 Place Specs Under the Relevant Package .claude/ Directory
- 6.3 How to Iterate on Specs When Requirements Change
1. Spec Structure & Content
1.1 Required Spec Document Structure
Impact: CRITICAL
Every spec document follows a consistent structure with these required elements in order:
- Title -
# Feature Name Specification - Metadata block - Status, Created, Last Updated, Purpose, Priority, Complexity
- Table of Contents - Numbered, linked
- Executive Summary - Overview, Key Metrics table, Goals, Rationale
- Current State Analysis - Existing code inventory, file paths, problems with evidence
- Architecture Design - Proposed solution with diagrams, before/after comparisons
- Implementation Plan - Phased breakdown with checkbox lists
- Testing Strategy - What to test per phase, manual and automated
- Success Criteria - Measurable, verifiable items
Incorrect:
# New Feature
## Implementation
1. Create the hook
2. Add the component
3. Wire it upCorrect:
# Feature Name Specification
**Status:** IN PROGRESS - Phase 1
**Created:** 2025-01-15
**Last Updated:** 2025-01-20
**Purpose:** Brief one-liner
**Priority:** HIGH
**Complexity:** MEDIUM
## Table of Contents
1. [Executive Summary](#executive-summary)
2. [Current State Analysis](#current-state-analysis)
3. [Architecture Design](#architecture-design)
4. [Implementation Plan](#implementation-plan)
5. [Testing Strategy](#testing-strategy)
6. [Success Criteria](#success-criteria)
## 1. Executive Summary
...
## 2. Current State Analysis
...1.2 Required Content for Each Spec Section
Impact: CRITICAL
Each section must contain specific types of information to prevent underspecification.
Executive Summary must include:
- One-paragraph overview
- Key Metrics table: Metric | Current | Target | Improvement
- Numbered goals (3-5)
- "Why This Matters" rationale
Current State Analysis must include:
- File location paths with line counts
- Hook/component inventory table: Name | Endpoint | Type | Used By
- Problems Identified with numbered descriptions and code snippets
Architecture Design must include:
- Before/after comparison table
- Type definitions or interface code blocks
- Decision rationale for key choices
Implementation Plan must include:
- Phased breakdown with
[ ]/[x]checkbox lists - File creation/modification/deletion inventory per phase
Testing Strategy must include:
- What to test per phase
- How to verify (manual steps, automated tests)
- Regression concerns
Success Criteria must include:
- Measurable items with specific numbers
- Before/after metric targets
1.3 Always Start With Current State Analysis
Impact: CRITICAL
Before proposing any changes, thoroughly document what exists today. This prevents building on incorrect assumptions.
Required analysis steps:
- Identify all affected files with paths and line counts
- Map every hook/component with its consumers
- Document current behavior with code snippets
- Identify specific problems with evidence (show the anti-pattern code)
- Note dependencies (what uses what, what will break if changed)
Incorrect:
## Architecture Design
We'll create a new V2 hook system that replaces everything.Correct:
## Current State Analysis
### Existing Implementation
The sender API is implemented across 3 files totaling 342 lines:
- `src/api/v1/sender.ts` (142 lines) - 7 hooks
- `src/hooks/useSenderPolling.ts` (89 lines) - polling wrapper
- `src/utils/senderTransforms.ts` (111 lines) - data transforms
### Hook Inventory
| Hook | Endpoint | Type | Used By |
|------|----------|------|---------|
| useSenders | GET /api/senders | Query + Polling | SenderList, SenderSelect |
| useCreateSender | POST /api/senders | Mutation | SenderForm |
### Problems Identified
1. **Global polling** - useSenders polls every 30s even when tab is hidden
```typescript
refetchInterval: 30000 // 2880 unnecessary requests/day
---
### 1.4 Spec as a Living Document
**Impact:** HIGH
Specs are updated throughout the implementation lifecycle. They are not write-once documents.
**When to update:**
- After each phase completes: add completion report section
- When problems are discovered: add to blockers/issues section
- When decisions change: update architecture section with date and rationale
- When metrics are measured: update metrics table with actual values
**Correct update pattern:**
```markdown
**Status:** COMPLETED
**Created:** 2025-10-27
**Last Updated:** 2025-11-10
**Phase 1 Completed:** 2025-11-07
**Phase 2 Completed:** 2025-11-07
**Phase 3 Completed:** 2025-11-10
## Recent Updates
**2025-11-10 - Phase 3 Completed**
- Cleanup phase finished, deleted 4 deprecated files
**2025-11-08 - CRITICAL ISSUE DISCOVERED**
- Build broken due to circular import
- Resolution: Moved type definitions to dedicated fileNever delete history -- mark old plans as superseded, not removed.
2. Phase Design
2.1 Phase 0 is Always Foundation Work
Impact: CRITICAL
Phase 0 handles infrastructure, setup, and cleanup that later phases depend on. It never includes feature logic.
Phase 0 typically includes:
- Deleting unused code identified during current state analysis
- Creating shared type definitions and interfaces
- Setting up key factories or shared utilities
- Backend optimizations that simplify frontend work
- Configuration changes (build, lint, test config)
- File structure creation (directories, barrel exports)
Incorrect:
## Phase 1: Implement Sender Migration
- [ ] Create V2 hook types
- [ ] Create V2 query keys
- [ ] Migrate SenderList component
- [ ] Delete old sender.tsCorrect:
## Phase 0: Foundation
- [ ] Delete 3 unused hooks identified in analysis
- [ ] Create shared type definitions in types/sender.types.ts
- [ ] Create query key factory in keys/senderKeys.ts
- [ ] Backend optimization: hardcode 'custom' type in controller
## Phase 1: Core V2 Structure
- [ ] Create query hooks
- [ ] Create mutation hooks2.2 How to Decompose Work Into Phases
Impact: CRITICAL
Each phase should be a cohesive, independently shippable unit that can be reviewed in a single PR.
Decomposition principles:
- Each phase produces a working (non-broken) state when merged
- Phases are grouped by domain/concern, not by file type
- Creation phases come before deletion phases
- Each phase is reviewable in a single PR
Common phase patterns:
For migrations:
- Phase 0: Cleanup / Foundation
- Phase 1: Create V2 structure (types, keys, queries, mutations)
- Phase 2: Component migration (swap imports, update logic)
- Phase 3: Delete V1 files, remove legacy patterns
- Phase 4: Testing and verification
For new features:
- Phase 0: Foundation (types, shared utilities)
- Phase 1: Core implementation (data model, main logic)
- Phase 2: UI integration
- Phase 3: Polish, edge cases, testing
For refactors:
- Phase 1: Setup new system alongside old (hybrid state)
- Phase 2: Migrate all consumers to new system
- Phase 3: Remove old system, cleanup
2.3 Order Phases by Dependency Chain
Impact: HIGH
Phases must be ordered so each phase's prerequisites are satisfied by earlier phases.
Dependency chain order:
- Backend changes -- always first, unblocks frontend
- Shared types and interfaces
- Utility/helper creation
- Core data layer (queries, mutations, keys)
- Component migration/creation
- Integration and wiring
- Cleanup and deletion of old code
- Testing and verification
Key rules:
- Types before implementations that use them
- Backend before frontend (when both change)
- Shared utilities before consumers
- Creation before deletion (create V2 before deleting V1)
- Never delete old code in the same phase as creating new code
3. Progress Tracking
3.1 Use Consistent Status Indicators
Impact: HIGH
Document-level status (metadata block):
READY FOR IMPLEMENTATION- Spec finalized, work not startedIN PROGRESS - Phase N- Currently being worked onCOMPLETED- All phases done
Phase-level progress tracker:
### Progress Tracker
- [x] **Phase 0: Foundation** - COMPLETED (2025-01-16)
- [x] **Phase 1: V2 Structure** - COMPLETED (2025-01-18)
- [ ] **Phase 2: Component Migration** - IN PROGRESS
- [ ] **Phase 3: Cleanup**Task-level checklists within phases:
## Phase 2: Component Migration
- [x] Migrate SenderList to V2 hooks
- [x] Migrate SenderForm to V2 hooks
- [ ] Migrate SenderDetail to V2 hooks3.2 Write Completion Reports Per Phase
Impact: HIGH
When a phase completes, add a completion report:
## Phase 2 Completion Report
**Completion Date:** 2025-01-22
**Status:** SUCCESSFUL
**Actual Effort:** ~3 hours
### Summary
Migrated all 8 components from V1 to V2 sender hooks.
### Key Achievements
- 8 components migrated
- Eliminated ReloadToken anti-pattern
- Added proper error boundaries
### Files Changed
- Created: 0 | Updated: 8 | Deleted: 0
### Issues Encountered
- SenderSelect relied on polling for live updates.
Resolution: Added WebSocket invalidation to Phase 3 scope.3.3 Include Before/After Metrics Tables
Impact: MEDIUM
Every spec should include a metrics table. Update with actual values after implementation.
| Metric | Current | Target | Actual | Improvement |
|--------|---------|--------|--------|-------------|
| Hooks | 7 | 6 | 6 | -1 hook |
| API Calls/Session | 5 | 1 | 1 | **-80%** |
| Type Safety | Mixed | Full | Full | 100% typed |
| Polling Requests/Day | 2880 | 0 | 0 | **-100%** |Common metrics: Hook count, network requests, cache scope, type safety, files changed, bundle size, build time.
4. PR Strategy
4.0 Feature PRs Always Target develop, Never main
Impact: CRITICAL
Every PR opened from a feature/* branch must target develop. Only release branches and hotfixes are allowed to target main.
Why: This repo follows GitFlow. main represents released code; develop is the integration branch. Merging a feature directly into main skips the release boundary, can ship unreleased work, and desyncs develop from main.
Branch → target table:
| Branch type | Branched from | PR targets |
feature/* | develop | develop |
feature/*-phase<N> | develop | develop |
release/YYYY-MM-DD | develop | main (then back-merge to develop) |
hotfix/* | main | main (then back-merge to develop) |
Always pass --base develop explicitly:
git checkout develop && git pull
git checkout -b feature/sender-api-migration
# ...commits...
gh pr create --base develop --head feature/sender-api-migration \
--title "Sender API - Phase 1"gh pr create defaults to the repo's default branch (often main) — never rely on the default. If a PR is mistakenly opened against main, fix it with gh pr edit <num> --base develop.
4.1 One PR Per Phase for Reviewability
Impact: HIGH
Each phase gets its own PR. This keeps reviews focused and merge conflicts manageable.
PR title format: "<Feature> - Phase N: <Description>"
When to split a phase into multiple PRs:
- Phase affects >20 files
- Phase crosses package boundaries
- Independent sub-domains within the phase
Incorrect: Single PR with 47 files spanning types, components, and cleanup.
Correct:
- PR 1: "Sender API - Phase 0: Foundation cleanup" (6 files)
- PR 2: "Sender API - Phase 1: V2 data layer" (6 files)
- PR 3: "Sender API - Phase 2: Component migration" (8 files)
- PR 4: "Sender API - Phase 3: V1 cleanup" (5 files)
4.2 Branch Naming Follows GitFlow Conventions
Impact: MEDIUM
Branch patterns:
- Single-phase features:
feature/<feature-name> - Multi-phase features:
feature/<feature-name>-phase<N> - Hotfixes:
hotfix/<description> - Releases:
release/YYYY-MM-DD
Merge strategies:
- Features to develop: Squash & Merge
- Releases to main: Merge commit
- Hotfixes to main: Merge commit, then sync to develop
4.3 Keep PRs Focused With Clear Scope Documentation
Impact: HIGH
PR description template:
## Summary
- What this PR does (1-3 bullet points)
## Changes
| Action | Files | Details |
|--------|-------|---------|
| Created | 6 | V2 query/mutation hooks |
| Updated | 1 | Barrel export |
## Metrics Impact
| Metric | Before | After |
|--------|--------|-------|
| API calls | 5 | 1 |
## Testing
- [x] Manual: Verified CRUD operations
- [x] Build: No errors
## Related
- Spec: `packages/autopilot/.claude/SENDER_MIGRATION_SPEC.md`
- Phase 1 PR: #142Scope rules:
- Never mix unrelated changes
- Bug fixes found during migration get separate PRs
- Link to spec document and prior phase PRs
5. Archival
5.1 When and How to Archive Completed Specs
Impact: MEDIUM
Archive criteria (ALL must be met):
- All phases marked as completed
- All PRs merged
- Completion summary written
- No remaining TODOs or blockers
Archive location: packages/<package-name>/.claude/archive/
File naming: Keep UPPERCASE_NAME_SPEC.md. Optionally append _COMPLETED_YYYY-MM-DD for major work.
What NOT to archive:
- Living reference documents still actively consulted
- Partially complete specs
5.2 Preserve Completion Notes and Learnings
Impact: MEDIUM
Before archiving, ensure the spec captures:
## Completion Summary
**Completed:** 2025-11-05
**Total Effort:** ~6 hours across 3 sessions
**PRs Merged:** 4
### Achievements
- 80% reduction in API calls
- Full type safety from API to component
### Key Decisions & Rationale
1. Kept useSenderStats separate - different refresh cadence
2. Added retry: false to mutations - prevented duplicate creates
### Learnings for Future Work
- Always verify backend type safety before frontend migration
- DevTools is essential for verifying cache invalidation
- Phase 0 cleanup saves significant time in later phases
### What Would Be Done Differently
- Would split Phase 2 into two PRs (8 components too many for one review)6. Workflow Collaboration
6.1 Iterative Planning Between AI and Developer
Impact: MEDIUM
The workflow is collaborative through a defined loop:
1. Discovery → Developer describes the feature/problem
2. Analysis → AI explores codebase, documents current state
3. Proposal → AI drafts spec with architecture and phases
4. Review → Developer reviews, provides feedback
5. Refinement → AI updates spec based on feedback
6. Approval → Developer confirms plan
7. Implementation → Phase-by-phase with per-phase PRs
8. Completion → Archive spec and capture learningsKey decision points requiring developer input:
- Architectural choices
- Scope decisions (in/out)
- Phase ordering priorities
- Naming conventions
Record decisions explicitly:
### Architectural Decision: Replace v2/deliveries/ - CONFIRMED
User selected: "Replace v2/deliveries/"
Rationale: Avoids duplicate endpoints and matches domain naming.Prevent scope creep with Non-Goals:
### Non-Goals
- Changing the WebSocket connection machine
- Adding features beyond the migration scope6.2 Place Specs Under the Relevant Package .claude/ Directory
Impact: MEDIUM
Placement rules:
- Specs go in
packages/<pkg>/.claude/ - Archived specs go in
packages/<pkg>/.claude/archive/ - Cross-package specs go in the most affected package
- File naming:
UPPERCASE_NAME_SPEC.md
6.3 How to Iterate on Specs When Requirements Change
Impact: LOW
Iteration patterns:
- Mid-phase discovery: Add to blockers section, update plan
- Scope change: Update Goals, add/remove phases, update metrics
- Architecture pivot: Document rejection and new approach with rationale
Update protocol:
- Always update
Last Updated:date - Add dated entry to "Recent Updates" (newest first)
- Update future phase descriptions if affected
- Never delete history -- use
~~strikethrough~~for superseded content
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

