john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: consolidate todo storage under .context/compound-engineering/todos/ (#361)

Browse Source
This commit is contained in:
Trevin Chow
2026-03-24 09:54:30 -07:00
committed by GitHub
parent 18d22afde2
commit 65e5621dbe
11 changed files with 306 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
plugins/compound-engineering/skills/file-todos/SKILL.md
View File

@@ -1,6 +1,6 @@
---
name: file-todos
description: This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes.
description: This skill should be used when managing the file-based todo tracking system in the .context/compound-engineering/todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with code review processes.
disable-model-invocation: true
---
@@ -8,26 +8,35 @@ disable-model-invocation: true
## Overview
The `todos/` directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.
The `.context/compound-engineering/todos/` directory contains a file-based tracking system for managing code review feedback, technical debt, feature requests, and work items. Each todo is a markdown file with YAML frontmatter and structured sections.
> **Legacy support:** During the transition period, always check both `.context/compound-engineering/todos/` (canonical) and `todos/` (legacy) when reading or searching for todos. Write new todos only to the canonical path. Unlike per-run scratch directories, `.context/compound-engineering/todos/` has a multi-session lifecycle -- do not clean it up as part of post-run scratch cleanup.
This skill should be used when:
- Creating new todos from findings or feedback
- Managing todo lifecycle (pending → ready → complete)
- Managing todo lifecycle (pending -> ready -> complete)
- Triaging pending items for approval
- Checking or managing dependencies
- Converting PR comments or code findings into tracked work
- Updating work logs during todo execution
## File Naming Convention
## Directory Paths
Todo files follow this naming pattern:
| Purpose | Path |
|---------|------|
| **Canonical (write here)** | `.context/compound-engineering/todos/` |
| **Legacy (read-only)** | `todos/` |
When searching or listing todos, always search both paths. When creating new todos, always write to the canonical path.
## File Naming Convention
```
{issue_id}-{status}-{priority}-{description}.md
```
**Components:**
- **issue_id**: Sequential number (001, 002, 003...) - never reused
- **issue_id**: Sequential number (001, 002, 003...) -- never reused
- **status**: `pending` (needs triage), `ready` (approved), `complete` (done)
- **priority**: `p1` (critical), `p2` (important), `p3` (nice-to-have)
- **description**: kebab-case, brief description
@@ -44,17 +53,17 @@ Todo files follow this naming pattern:
Each todo is a markdown file with YAML frontmatter and structured sections. Use the template at [todo-template.md](./assets/todo-template.md) as a starting point when creating new todos.
**Required sections:**
- **Problem Statement** - What is broken, missing, or needs improvement?
- **Findings** - Investigation results, root cause, key discoveries
- **Proposed Solutions** - Multiple options with pros/cons, effort, risk
- **Recommended Action** - Clear plan (filled during triage)
- **Acceptance Criteria** - Testable checklist items
- **Work Log** - Chronological record with date, actions, learnings
- **Problem Statement** -- What is broken, missing, or needs improvement?
- **Findings** -- Investigation results, root cause, key discoveries
- **Proposed Solutions** -- Multiple options with pros/cons, effort, risk
- **Recommended Action** -- Clear plan (filled during triage)
- **Acceptance Criteria** -- Testable checklist items
- **Work Log** -- Chronological record with date, actions, learnings
**Optional sections:**
- **Technical Details** - Affected files, related components, DB changes
- **Resources** - Links to errors, tests, PRs, documentation
- **Notes** - Additional context or decisions
- **Technical Details** -- Affected files, related components, DB changes
- **Resources** -- Links to errors, tests, PRs, documentation
- **Notes** -- Additional context or decisions
**YAML frontmatter fields:**
```yaml
@@ -69,20 +78,21 @@ dependencies: ["001"] # Issue IDs this is blocked by
## Common Workflows
> **Tool preference:** Use native file-search (e.g., Glob in Claude Code) and content-search (e.g., Grep in Claude Code) tools instead of shell commands for finding and reading todo files. This avoids unnecessary permission prompts in sub-agent workflows. Use shell only for operations that have no native equivalent (e.g., `mv` for renames, `mkdir -p` for directory creation).
### Creating a New Todo
**To create a new todo from findings or feedback:**
1. Determine next issue ID: `ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1`
2. Copy template: `cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md`
3. Edit and fill required sections:
1. Ensure directory exists: `mkdir -p .context/compound-engineering/todos/`
2. Determine next issue ID by searching both canonical and legacy paths for files matching `[0-9]*-*.md` using the native file-search/glob tool. Extract the numeric prefix from each filename, find the highest, and increment by one. Zero-pad to 3 digits (e.g., `007`).
3. Read the template at [todo-template.md](./assets/todo-template.md), then write it to `.context/compound-engineering/todos/{NEXT_ID}-pending-{priority}-{description}.md` using the native file-write tool.
4. Edit and fill required sections:
- Problem Statement
- Findings (if from investigation)
- Proposed Solutions (multiple options)
- Acceptance Criteria
- Add initial Work Log entry
4. Determine status: `pending` (needs triage) or `ready` (pre-approved)
5. Add relevant tags for filtering
5. Determine status: `pending` (needs triage) or `ready` (pre-approved)
6. Add relevant tags for filtering
**When to create a todo:**
- Requires more than 15-20 minutes of work
@@ -101,21 +111,19 @@ dependencies: ["001"] # Issue IDs this is blocked by
### Triaging Pending Items
**To triage pending todos:**
1. List pending items: `ls todos/*-pending-*.md`
1. Find pending items using the native file-search/glob tool with pattern `*-pending-*.md` in both directory paths.
2. For each todo:
- Read Problem Statement and Findings
- Review Proposed Solutions
- Make decision: approve, defer, or modify priority
3. Update approved todos:
- Rename file: `mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md`
- Update frontmatter: `status: pending` → `status: ready`
- Update frontmatter: `status: pending` -> `status: ready`
- Fill "Recommended Action" section with clear plan
- Adjust priority if different from initial assessment
4. Deferred todos stay in `pending` status
**Use slash command:** `/triage` for interactive approval workflow
Load the `triage` skill for an interactive approval workflow.
### Managing Dependencies
@@ -126,31 +134,20 @@ dependencies: ["002", "005"] # This todo blocked by issues 002 and 005
dependencies: [] # No blockers - can work immediately
```
**To check what blocks a todo:**
```bash
grep "^dependencies:" todos/003-*.md
```
**To check what blocks a todo:** Use the native content-search tool (e.g., Grep in Claude Code) to search for `^dependencies:` in the todo file.
**To find what a todo blocks:**
```bash
grep -l 'dependencies:.*"002"' todos/*.md
```
**To find what a todo blocks:** Search both directory paths for files containing `dependencies:.*"002"` using the native content-search tool.
**To verify blockers are complete before starting:**
```bash
for dep in 001 002 003; do
[ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete"
done
```
**To verify blockers are complete before starting:** For each dependency ID, use the native file-search/glob tool to look for `{dep_id}-complete-*.md` in both directory paths. Any missing matches indicate incomplete blockers.
### Updating Work Logs
**When working on a todo, always add a work log entry:**
When working on a todo, always add a work log entry:
```markdown
### YYYY-MM-DD - Session Title
**By:** Claude Code / Developer Name
**By:** Agent name / Developer Name
**Actions:**
- Specific changes made (include file:line references)
@@ -172,82 +169,62 @@ Work logs serve as:
### Completing a Todo
**To mark a todo as complete:**
1. Verify all acceptance criteria checked off
2. Update Work Log with final session and results
3. Rename file: `mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md`
4. Update frontmatter: `status: ready` → `status: complete`
5. Check for unblocked work: `grep -l 'dependencies:.*"002"' todos/*-ready-*.md`
4. Update frontmatter: `status: ready` -> `status: complete`
5. Check for unblocked work: search both directory paths for `*-ready-*.md` files containing `dependencies:.*"{issue_id}"` using the native content-search tool
6. Commit with issue reference: `feat: resolve issue 002`
## Integration with Development Workflows
| Trigger | Flow | Tool |
|---------|------|------|
| Code review | `/ce:review` → Findings → `/triage` → Todos | Review agent + skill |
| Beta autonomous review | `/ce:review-beta mode:autonomous` → Downstream-resolver residual todos → `/resolve-todo-parallel` | Review skill + todos |
| PR comments | `/resolve_pr_parallel` → Individual fixes → Todos | gh CLI + skill |
| Code TODOs | `/resolve-todo-parallel` → Fixes + Complex todos | Agent + skill |
| Planning | Brainstorm → Create todo → Work → Complete | Skill |
| Feedback | Discussion → Create todo → Triage → Work | Skill + slash |
| Code review | `/ce:review` -> Findings -> `/triage` -> Todos | Review agent + skill |
| Beta autonomous review | `/ce:review-beta mode:autonomous` -> Downstream-resolver residual todos -> `/resolve-todo-parallel` | Review skill + todos |
| PR comments | `/resolve_pr_parallel` -> Individual fixes -> Todos | gh CLI + skill |
| Code TODOs | `/resolve-todo-parallel` -> Fixes + Complex todos | Agent + skill |
| Planning | Brainstorm -> Create todo -> Work -> Complete | Skill |
| Feedback | Discussion -> Create todo -> Triage -> Work | Skill |
## Quick Reference Commands
## Quick Reference Patterns
Use the native file-search/glob tool (e.g., Glob in Claude Code) and content-search tool (e.g., Grep in Claude Code) for these operations. Search both canonical and legacy directory paths.
**Finding work:**
```bash
# List highest priority unblocked work
grep -l 'dependencies: \[\]' todos/*-ready-p1-*.md
# List all pending items needing triage
ls todos/*-pending-*.md
# Find next issue ID
ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'
# Count by status
for status in pending ready complete; do
echo "$status: $(ls -1 todos/*-$status-*.md 2>/dev/null | wc -l)"
done
```
| Goal | Tool | Pattern |
|------|------|---------|
| List highest priority unblocked work | Content-search | `dependencies: \[\]` in `*-ready-p1-*.md` |
| List all pending items needing triage | File-search | `*-pending-*.md` |
| Find next issue ID | File-search | `[0-9]*-*.md`, extract highest numeric prefix |
| Count by status | File-search | `*-pending-*.md`, `*-ready-*.md`, `*-complete-*.md` |
**Dependency management:**
```bash
# What blocks this todo?
grep "^dependencies:" todos/003-*.md
# What does this todo block?
grep -l 'dependencies:.*"002"' todos/*.md
```
| Goal | Tool | Pattern |
|------|------|---------|
| What blocks this todo? | Content-search | `^dependencies:` in the specific todo file |
| What does this todo block? | Content-search | `dependencies:.*"{id}"` across all todo files |
**Searching:**
```bash
# Search by tag
grep -l "tags:.*rails" todos/*.md
# Search by priority
ls todos/*-p1-*.md
# Full-text search
grep -r "payment" todos/
```
| Goal | Tool | Pattern |
|------|------|---------|
| Search by tag | Content-search | `tags:.*{tag}` across all todo files |
| Search by priority | File-search | `*-p1-*.md` (or p2, p3) |
| Full-text search | Content-search | `{keyword}` across both directory paths |
## Key Distinctions
**File-todos system (this skill):**
- Markdown files in `todos/` directory
- Development/project tracking
- Markdown files in `.context/compound-engineering/todos/` (legacy: `todos/`)
- Development/project tracking across sessions and agents
- Standalone markdown files with YAML frontmatter
- Used by humans and agents
- Persisted to disk, cross-agent accessible
**Rails Todo model:**
- Database model in `app/models/todo.rb`
- User-facing feature in the application
- Active Record CRUD operations
- Different from this file-based system
**TodoWrite tool:**
**In-session task tracking (e.g., TaskCreate/TaskUpdate in Claude Code, update_plan in Codex):**
- In-memory task tracking during agent sessions
- Temporary tracking for single conversation
- Not persisted to disk
- Different from both systems above
- Not persisted to disk after session ends
- Different purpose: use for tracking steps within a session, not for durable cross-session work items