feat: created the architect and gatekeeper agents for dramatically improved coding performance

2026-07-29 11:23:52 -06:00
parent 38ba303c3c
commit 57b72702b2
8 changed files with 1075 additions and 1 deletions
@@ -0,0 +1,87 @@
+---
+description: File-based task tracking for plan-driven runs on any project. Defines the TASK-NNN directory schema (index.md + append-only log.md), the frontmatter lifecycle (pending/in-progress/blocked/complete), numbering, the completion protocol, and follow-up task creation. The tasks directory on disk is the durable run state - it survives context compression. Grants filesystem access for managing task files.
+enabled_tools: fs_read, fs_grep, fs_glob, fs_ls, fs_cat, fs_write, fs_patch, fs_mkdir
+---
+You are tracking implementation tasks as files. The task directory is the durable source of truth for run state — anything that lives only in chat history is lost to context compression. Keep it current at every state change, not in batches.
+
+## Layout
+
+```
+<plans_dir>/
+  PLAN-<slug>.md                  # the plan (see design-session / plan-authoring)
+  tasks/
+    TASK-001-<slug>/
+      index.md                    # current state: frontmatter + What/Steps/Acceptance criteria
+      log.md                      # append-only audit trail
+    TASK-002-<slug>/
+      ...
+```
+
+## index.md schema
+
+```markdown
+---
+title: <short imperative title>
+status: pending        # pending | in-progress | blocked | complete
+type: feature          # feature | chore | followup
+points: 1.0            # engineer-days; ~1.0 per the sizing rule
+plan: PLAN-<slug>.md
+blocked_by: []         # TASK ids that must be complete first
+created: YYYY-MM-DD
+---
+
+## What
+
+One paragraph: what this task produces, named concretely (files, symbols, behaviors).
+
+## Steps
+
+- [ ] Concrete step — name the file, function, or migration
+- [ ] ...
+
+## Acceptance criteria
+
+- [ ] Observable behavior, measurable ("returns 429 after 3 failed attempts")
+- [ ] ...
+```
+
+Status lives in frontmatter — there are no lifecycle directories. `status: complete` plus all boxes checked IS done.
+
+## log.md conventions
+
+Append-only. Each entry is an H2: `## YYYY-MM-DD — <short label>` (`created`, `started`, `implemented`, `diverged`, `completed`, ...). Body is 1-3 sentences of prose; structured data lives in markdown links (branch URLs, commit SHAs, PR links). Never rewrite an old entry — add a new one.
+
+## Numbering
+
+Scan `tasks/TASK-*` for the highest NNN and increment (zero-padded to 3). This assumes a single writer per plans directory; if multiple agents or people share one, serialize task creation.
+
+## Lifecycle protocol
+
+| Transition | Do |
+|---|---|
+| Create | `fs_mkdir` the dir; write `index.md` (status: pending) + `log.md` with a `created` entry |
+| Claim | frontmatter `status: in-progress`; log `started` (note the branch + base SHA) |
+| Blocked | `status: blocked`; log why and what unblocks it |
+| Complete | Check off every Step and Acceptance criterion (verified, not aspirational); log `completed` with commit SHAs AND any follow-ups reported by the implementer, VERBATIM; set `status: complete` |
+
+Never mark a criterion checked without evidence. Never batch state changes — update at the moment of transition.
+
+## Follow-up tasks
+
+When implementation surfaces manual/out-of-scope actions (secrets to create, cloud roles to provision, console steps, cross-repo changes): create a task per item (group small related ones) with `type: followup`, `status: pending`, the WHAT/WHERE/WHY/WHEN in its What section, and a note of which TASK surfaced it. Follow-ups are deliverables to hand to the user — never implement them in the current run.
+
+## Consistency checks (run at the end of a run)
+
+- Every task dir has both `index.md` and `log.md`.
+- Every `blocked_by` reference resolves to an existing task.
+- No task is `complete` with unchecked Steps/Acceptance criteria.
+- Every `complete` task's log has a `completed` entry with commit references.
+- The PLAN's breakdown table rows all map to task dirs (and vice versa).
+
+## Anti-patterns
+
+- Run state that exists only in chat — session ids, decisions, and follow-ups belong in task files.
+- `status: complete` with unchecked boxes, or checked boxes without evidence.
+- Rewriting log history instead of appending.
+- Hand-picking a task number without scanning (collisions).
+- Follow-ups mentioned in a summary but never materialized as task files.