engsys 1.0.0

package/core/workflows/agent-implementation-workflow.md

@@ -0,0 +1,346 @@
+# Agent Implementation Workflow
+
+Implement tracker issues using Git worktrees for isolation. The default unit is a **phase PR**: all issues in one project phase become individual commits in one branch, one worktree, one PR.
+
+If a project has no phases, implement all selected issues in one PR. If there is only one issue, the PR naturally contains one issue. Do not split into one PR per issue unless the human explicitly asks.
+
+Work-item operations (claim, fetch state, record findings, link/close) go through the project's installed **issue-tracker skill** (`.claude/skills/issue-tracker-*/`) via its contract operations (`get-issue`, `update-issue`, `comment-issue`, `link-pr`). The skill maps them onto the active backend; the GitHub `gh` commands shown below are what it runs on a GitHub project. PR creation (`gh pr create`), CI, and worktree/git mechanics stay on GitHub regardless of tracker.
+
+## Start Command Authorization
+
+When a human says `Start on Project <number>`, `Start on issue <number>`, `Implement Project <number>`, or equivalent implementation wording while pointing at this workflow, treat that as explicit authorization to complete the normal agent implementation cycle:
+
+- scope the batch
+- create the worktree and branch
+- edit files
+- create the issue-scoped implementation commits
+- run validation
+- run the local code review and resolve findings
+- push the agent branch
+- open the PR and record the review findings
+
+Do not pause after validation solely to ask whether commits, push, or PR creation are allowed. This workflow is the authorization for those routine implementation steps.
+
+Still require a separate explicit human instruction before merging PRs, pushing to `main`, force-pushing anything except the active agent branch with `--force-with-lease` during documented rebase recovery, or running destructive cleanup outside the completed/merged workflow.
+
+---
+
+## Phase 0: Scope the Batch
+
+Before creating the worktree:
+
+- Review `docs/agent-lessons/` so recent mistakes and tool lessons are fresh in context.
+- Fetch the current issue/project state from the tracker via the skill's `get-issue` / `query-board` operations, not stale local notes.
+- Identify the implementation batch:
+  - phased project: one phase = one PR
+  - unphased project: all selected issues = one PR
+  - single issue: one issue = one PR
+- Assign every issue in the batch to yourself via the skill's `update-issue` operation.
+- Build a commit plan: each issue gets its own implementation commit referencing that issue number.
+
+```bash
+# GitHub realization of update-issue (claim):
+gh issue edit <number> --add-assignee "@me"
+```
+
+---
+
+## Phase 1: Setup
+
+```bash
+# From the main repo root, ensure main is current
+git fetch origin && git checkout main && git pull --ff-only origin main
+
+# If pull --ff-only fails (local main diverged from origin/main due to squash merges),
+# reset local main before creating the worktree:
+#   git reset --hard origin/main
+# OR create the worktree directly from origin/main (safest):
+#   git worktree add ../worktrees/<slug> -b agent/<slug> origin/main
+
+# Create the worktree AND branch in one command (-b flag is CRITICAL)
+git worktree add ../worktrees/<phase-or-project-slug> -b agent/<phase-or-project-slug> origin/main
+
+cd ../worktrees/<phase-or-project-slug>
+# install deps + run any codegen the project requires (see CLAUDE.md)
+```
+
+Use a branch slug that describes the batch, not just the first issue. Examples:
+
+- `agent/project-11-phase-2-enrichment`
+- `agent/settings-billing-metrics`
+- `agent/957-tenant-switching` for a single-issue PR
+
+> **Project bootstrap:** a fresh worktree has no installed dependencies and may need codegen (client generation, schema build, etc.). Run the project's bootstrap (`CLAUDE.md` § setup) inside the worktree before building.
+
+---
+
+## Phase 2: Implement
+
+- Edit files inside the worktree only.
+- Complete one issue at a time and commit it before moving to the next issue.
+- Each implementation commit must reference the issue it satisfies: `feat(<scope>): add invite endpoint (#131)`.
+- **File-overlap exception:** when two issues legitimately touch the same source files (same controller, DTO, service), forcing a split creates a broken intermediate commit. Co-commit those issues instead and cite all issue numbers in the subject: `feat(<scope>): PATCH /auth/me + PATCH /auth/me/default-tenant (#1565, #1566)`. The PR body's `Closes #` lines still auto-close all issues on merge.
+- Keep review-fix commits (from the local review or later human review) as follow-ups after the issue commits.
+- Use the `tmp/` folder for commit messages and PR bodies — **never HEREDOC**.
+
+```bash
+# Write the commit message to a file, then commit
+git commit -F tmp/commit-msg-<issue-number>.txt
+```
+
+---
+
+## Phase 3: Verify + Review Before Push
+
+When all issue commits are complete, validate locally **and run the local code review** before pushing or opening the PR. Go in clean: a clean local review means the first CI run is also the last.
+
+```bash
+git fetch origin                       # local main is often stale in a worktree
+<the project's pre-push gate / precheck>   # build, lint, format, unit tests, path-gated gates
+<a local code review against origin/main>  # built-in /code-review skill, or the project's CLI reviewer
+```
+
+If any gate fails, fix locally and re-run. The project's pre-push gate (and the local pre-push hook, if it has one) is the contract; see `/pre-push`.
+
+For the review: fix **Critical** and **Warning** findings, **Info** at discretion, then re-run once to confirm clean. Cap the loop at ~2 passes — don't grind. Keep the findings — you'll post them on the PR in Phase 4.
+
+---
+
+## Phase 4: Push + Create PR (draft-first)
+
+After local verification passes, push once and create the PR as **draft**.
+
+```bash
+git push -u origin agent/<phase-or-project-slug>
+```
+
+Write the PR body to `tmp/` first:
+
+```bash
+# 1. Write the PR body using the Write tool -> tmp/pr-body-<phase-or-project-slug>.md
+#    Include: summary, issue list, Closes keywords, test plan
+
+# 2. Create the PR as DRAFT (defers any expensive ready-for-review CI matrix)
+gh pr create \
+  --base main \
+  --draft \
+  --title "<type>(<scope>): <batch description>" \
+  --body-file tmp/pr-body-<phase-or-project-slug>.md \
+  --label "<labels>"
+
+# 3. Clean up the tmp file
+rm tmp/pr-body-<phase-or-project-slug>.md
+```
+
+If the project gates expensive CI (E2E / a11y / flake matrices) behind the ready-for-review transition, draft-first defers it until you flip the PR ready.
+
+Link/close the work items per the skill's `link-pr` operation. On GitHub that means one closing keyword per issue in the PR body — GitHub only closes the first issue when multiple are comma-separated on one line (`Closes #1, #2, #3` closes only `#1`):
+
+```markdown
+Closes #1
+Closes #2
+Closes #3
+```
+
+**Record the review findings on the work item.** After the PR is created, post the Phase 3 review findings via the skill's `comment-issue` operation, as one comment that contains a stable marker (e.g. `<!-- local-review-findings -->`). This is the durable record the [closeout ceremony](project-closeout-ceremony.md) mines for recurring mistake families. Write the body to `tmp/` first; on GitHub the skill posts it on the PR:
+
+```bash
+gh pr comment <pr-number> --body-file tmp/review-findings-<pr>.md
+```
+
+```markdown
+<!-- local-review-findings -->
+
+**Local code review** (pre-push) — <N> findings
+
+- **[Critical]** <title> — fixed in <sha>
+- **[Warning]** <title> — fixed in <sha>
+- **[Warning]** <title> — not changed: <reason>
+- **[Info]** <title> — deferred (see #<issue>)
+```
+
+If the review surfaced zero findings, still post the comment with "0 findings" so closeout has a complete corpus.
+
+---
+
+## Phase 5: Mark Ready for Review
+
+The PR is draft and already locally reviewed (Phase 3). Once the local review is resolved, the pre-push gate is green, and the cheap draft CI passes, mark the PR ready:
+
+```bash
+gh pr ready <pr-number>
+```
+
+If the project's full CI matrix fires on the `ready_for_review` transition, be confident before flipping it — don't mark ready with unresolved Critical/Warning findings or a red gate; that's what draft is for.
+
+If a finding exposes a product or architecture decision rather than a clear fix, **stop and ask the human** instead of guessing.
+
+---
+
+## Phase 6: Reflect + Update Agent Memory
+
+After final review-response commits are made, reflect before handing the PR to the human.
+
+Ask:
+
+- Did I struggle to call the right tools?
+- Did I miss a critical rule, project doc, issue detail, service boundary, or architecture context?
+- Did tests, CI, the local review, or the human catch something I should have caught earlier?
+- What went wrong that future me can avoid?
+
+Actions:
+
+- Create or update LLM-optimized notes in `docs/agent-lessons/`.
+- Update the relevant agent profile (`.claude/agents/*.md`) if role behavior should change.
+- Create or update rules, prompt docs, or other instructions when the lesson should be automatically applied.
+- If the lesson generalizes beyond this project, open a PR back to the engsys `lessons-library/`.
+- Commit these learning/instruction changes as a final PR commit.
+
+Write lessons for machine retrieval, not human reading: short headings, trigger phrases, failure mode, correct behavior, commands/files to check, and links to authoritative docs.
+
+---
+
+## Phase 7: Human Review + Merge
+
+After the local review findings are handled and learning updates are committed:
+
+- Push the final branch.
+- Ensure the PR body and test plan are current.
+- Wait for all required CI workflows to pass.
+- Human in the loop performs the final review.
+- Human squash-merges the PR when satisfied.
+
+Agents do not merge their own implementation PRs unless the human explicitly asks.
+
+---
+
+## Phase 8: Cleanup After Merge
+
+After the PR is squash-merged:
+
+```bash
+# From the main repo root
+git checkout main
+git pull --ff-only origin main
+
+# Empty the worktree directory first if needed (node_modules/dist/build artifacts can block removal)
+git worktree remove ../worktrees/<phase-or-project-slug> --force
+git branch -d agent/<phase-or-project-slug>
+git worktree prune
+```
+
+If the branch was already deleted remotely by the tracker, local branch deletion is still required. If `git branch -d` refuses because a squash merge changed commit IDs, verify the PR is merged, then use `git branch -D agent/<phase-or-project-slug>`.
+
+---
+
+## Stacked Branches
+
+Prefer one phase PR from `main`. Use stacked branches only when one batch must build on unreleased work from another branch.
+
+```bash
+git worktree add ../worktrees/<child-slug> agent/<parent-slug> -b agent/<child-slug>
+```
+
+This creates a dependency: the parent PR must merge before the child PR can merge cleanly.
+
+After the parent PR merges:
+
+```bash
+cd ../worktrees/<child-slug>
+git fetch origin
+git rebase origin/main
+```
+
+Git may skip commits that are now on main. If it stops on a duplicate already-merged commit, skip it:
+
+```bash
+git rebase --skip
+```
+
+After a clean rebase:
+
+```bash
+git log --oneline origin/main..HEAD
+git push --force-with-lease origin agent/<child-slug>
+```
+
+---
+
+## Rules
+
+| Rule                       | Detail                                                                                                                                                                                          |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Batch by phase**         | One phase/project batch = one branch, one worktree, one PR                                                                                                                                      |
+| **Commit by issue**        | Each issue gets its own implementation commit with a `#issue` reference. **File-overlap exception** (Phase 2): co-commit issues that touch the same files, cite all issue numbers in the subject. The PR body's `Closes #` lines still auto-close every issue on merge. |
+| **Validate before PR**     | Run the project's pre-push gate / precheck (build, lint, tests, plus path-gated checks for E2E, migrations, IaC, containers). The local pre-push hook runs it automatically if the project has one. See `/pre-push`. |
+| **Draft-first PR**         | Always `gh pr create --draft`. Mark **Ready for review** (`gh pr ready`) only after the local review is resolved and the gate is green — that triggers any expensive ready-for-review CI matrix. |
+| **Local review**          | Run a local code review **before push** (Phase 3); fix Critical + Warning, re-run clean (~2 passes max). After opening the PR, post findings onto the work item (skill `comment-issue`) as one marked comment for closeout to mine.        |
+| **Reflect before handoff** | Update `docs/agent-lessons/`, the agent profile, and rules/instructions when the PR reveals a reusable lesson; PR generalizable lessons back to the engsys lessons-library.                      |
+| **tmp/ always**            | Commit messages, PR bodies, issue bodies — never HEREDOC or pipe                                                                                                                                |
+| **No commit pause**        | A start/implement command for this workflow authorizes routine commits, branch push, PR creation, and local-review fixes                                                                        |
+
+---
+
+## Completion Checklist
+
+```text
+[ ] docs/agent-lessons/ reviewed before starting
+[ ] Batch scope selected: phase, unphased project, or single issue
+[ ] Worktree and branch created for the batch (from origin/main, -b flag)
+[ ] Every issue assigned to the implementer
+[ ] Each issue has its own implementation commit referencing #N (or a single co-commit citing all overlapping issue numbers per the file-overlap exception)
+[ ] Pre-push gate passes (build, lint, tests, and path-gated gates)
+[ ] Local review run; Critical + Warning findings resolved, re-run clean
+[ ] Branch pushed to origin
+[ ] PR created as DRAFT, work items linked/closed per link-pr (GitHub: one Closes line per issue)
+[ ] Review findings posted onto the work item via comment-issue, as a marked comment (or "0 findings")
+[ ] PR marked Ready for review (gh pr ready <n>)
+[ ] Reflection completed and learning/profile/rule updates committed if needed
+[ ] CI green and PR ready for human review
+[ ] Human squash-merged the PR
+[ ] main checked out and pulled
+[ ] Worktree removed, local branch deleted, worktrees pruned
+```
+
+---
+
+## Troubleshooting
+
+**Worktree creation fails** — You probably created the branch first. Delete it and use the `-b` flag:
+
+```bash
+git branch -d agent/<phase-or-project-slug>
+git worktree add ../worktrees/<phase-or-project-slug> -b agent/<phase-or-project-slug> origin/main
+```
+
+**Worktree remove fails — "Directory not empty"** — Empty the worktree directory before `git worktree remove` (e.g. leftover `node_modules`, `dist`, build output). From the repo root:
+
+```bash
+rm -rf ../worktrees/<phase-or-project-slug>/*
+git worktree remove ../worktrees/<phase-or-project-slug> --force
+git worktree prune
+```
+
+**Build errors about generated code** — Codegen wasn't run. Re-run the project's codegen step inside the worktree.
+
+**Merge conflicts** — Rebase on main:
+
+```bash
+git fetch origin && git rebase origin/main
+```
+
+If the rebase stops on a commit that was already merged to main, skip it:
+
+```bash
+git rebase --skip
+```
+
+Never `git rebase --abort` just because of "already applied" warnings; that is expected when rebasing stacked branches.
+
+**Local main diverged from origin/main** — Fix with rebase, not merge:
+
+```bash
+git fetch origin && git rebase origin/main
+```
+
+**Batch feels too large** — Stop and ask the human before splitting. The default remains one PR per phase or unphased project, not one PR per issue.

package/core/workflows/generate-project.md

@@ -0,0 +1,258 @@
+# Generate Project Workflow
+
+Use this workflow when the operator asks to generate a feature design, spec, plan, or project from a goal. Output is a reviewed draft spec in `docs/specs/`, an organized tracker project, phased issues, and updated agent learning where useful.
+
+Invocation examples:
+
+```text
+/generate-project <goal> [attachments...]
+generate project: <goal>
+build a feature spec/plan for <goal>
+```
+
+---
+
+## Operating Rules
+
+- Explore first. Do not ask generic questions until you have read relevant code, docs, existing issues/projects, and attachments.
+- Batch clarifying questions. Ask once, wait for answers, then proceed.
+- Use subagents for perspective, not delegation drift. The parent agent owns the spec and reconciles conflicts.
+- Make the spec the shared source of truth. Every subagent enriches `docs/specs/<slug>.md` directly or returns structured content for the parent to merge.
+- Tracker project + issue writes go through the project's installed **issue-tracker skill** (`.claude/skills/issue-tracker-*/`) and its contract operations (`create-issue`, `create-board`, `add-to-board`, `set-board-field`, `query-board`). The skill maps them onto the active backend; on GitHub it uses `gh` (ProjectV2 MCP tools are unsupported there, so the skill drives `gh project` / `gh api graphql`).
+- Write issue bodies to `tmp/` and create them via the skill's `create-issue` operation (GitHub: `gh issue create --body-file`). Never HEREDOC issue bodies — the tmp/-file discipline is universal.
+- Issue-body invariants (every one of these has been a sanity-check finding at least once):
+  - Every body carries one context line: `Part of [<project name> — project <N>](<board url>) · spec: docs/specs/<slug>.md`. Section citations ("spec §2.2") are unresolvable without it.
+  - No placeholder cross-references (`#BUNDLE`, `#SERIALIZER`, ALL-CAPS tokens). Create issues in dependency order or backfill numbers after creation, then **grep all bodies for placeholders** before declaring done. Bare `#<small-number>` shorthand for non-issue concepts (e.g. "punch item 12") autolinks to the wrong issue — write "punch item 12" or use the real issue #.
+  - Counts in acceptance criteria must be **call sites, not grep lines** (imports inflate grep counts) — state the exact grep that reproduces the number inside the issue.
+  - One implementation PR per phase means a phase must be one-PR-sized; split infra (which may trigger a deploy workflow) from app code into separate phases.
+- Optimize final specs, lessons, rules, and agent instructions for future LLM retrieval.
+
+---
+
+## Phase 0: Intake
+
+The operator provides:
+
+- The goal or product outcome.
+- Relevant attachments: screenshots, docs, links, logs, issue lists, customer notes, designs, or code pointers.
+- Optional constraints: deadline, scope, target user, tier, services, non-goals, project naming.
+
+Record initial assumptions in the draft spec later, but do not freeze them before exploration.
+
+---
+
+## Phase 1: Explore Context
+
+Build informed questions from evidence.
+
+Read:
+
+- `docs/agent-lessons/` (and the engsys lessons-library if linked)
+- `docs/architecture/` relevant pages
+- project rules / `CLAUDE.md`
+- `.claude/agents/{leith,melvin,nyx,marcelo,jody}.md`
+- Existing specs in `docs/specs/`
+- Related source files, routes, services, schemas, UI components, tests, seed scripts
+- Provided attachments and linked resources
+- Existing tracker issues/projects if the goal references them
+
+Capture: user/persona affected, current behavior, data model & API surface touched, service boundaries, security/auth/tenant implications, test surfaces and existing coverage, and unknowns that materially change product, architecture, security, testing, or plan shape.
+
+Do not over-explore. Stop when questions are specific and answerable.
+
+---
+
+## Phase 2: Ask Clarifying Questions
+
+Ask the operator one batched set of clarifying questions. Prefer structured options when possible.
+
+Quality bar: no questions answerable from repo/docs; no more than 5–8 unless genuinely ambiguous; each question explains the decision it unlocks; include recommended defaults when useful.
+
+Good categories: target users and primary job-to-be-done; must-have vs deferred; data visibility and tenant boundaries; integration/source-of-truth choices; rollout/entitlement/tier constraints; success metrics; design constraints from attachments.
+
+After the operator answers, update assumptions and proceed. If answers conflict with repo reality, call that out and choose the safer interpretation.
+
+---
+
+## Phase 3: Start Draft Spec
+
+Create `docs/specs/<feature-slug>.md`:
+
+```markdown
+# <Feature / Project Name>
+
+Status: Draft
+Owner: <operator or team>
+Generated: <date>
+
+## Goal
+
+## Context
+
+## Operator Inputs
+
+## Assumptions
+
+## Non-Goals
+
+## Open Questions
+
+## Product and UX Specification
+
+## Architecture Specification
+
+## Security and Privacy Specification
+
+## Testing Strategy
+
+## Phased Project Plan
+
+## Tracker Project and Issues
+
+## Implementation Notes
+
+## Review Checklist
+```
+
+Frame the goal and context before launching subagents so each receives the same baseline.
+
+---
+
+## Phase 4: Design Loop
+
+Launch Leith and Melvin in parallel when possible, then Nyx, then reconcile, then Marcelo, then Jody. Pass each subagent the goal, answered clarifications, an attachments summary, the spec path, and the exact requested output.
+
+Subagents do not automatically know parent context. Include enough detail in every prompt for autonomous work.
+
+### 4A: Leith — Product/UX
+
+Enrich the spec with: product problem and target persona; user stories and jobs-to-be-done; happy path, sad paths, empty/loading/error states; information architecture and navigation entry points; UI behavior, copy intent, accessibility expectations; acceptance criteria from a user perspective; product tradeoffs and recommended scope boundaries. Returns structured markdown for `Product and UX Specification`.
+
+### 4B: Melvin — Architecture
+
+Enrich the spec with: whole-app architecture impact; affected services, modules, APIs, schemas, queues, jobs, integrations; data ownership and consistency model; latency, scale, cost, observability, failure modes; migration/backfill/rollout strategy; implementation invariants and constraints; architecture acceptance criteria. Returns structured markdown for `Architecture Specification`.
+
+### 4C: Nyx — Security
+
+Given the merged Leith+Melvin draft, enrich with: threat model and trust boundaries; tenant isolation risks; authn/authz requirements; abuse cases and attacker stories; input validation and output encoding; secrets, logging, audit, PII, data retention; security tests and required mitigations; must-fix design changes vs acceptable follow-ups. Returns `Security and Privacy Specification` and a list of required changes.
+
+### 4D: Reconcile Nyx Findings
+
+If Nyx identifies required changes: send product/interaction findings back to Leith, architecture/platform findings back to Melvin; ask for revised spec patches (not new standalone opinions); merge revisions; keep unresolved disagreements in `Open Questions` with a recommended decision. **Do not proceed to testing strategy while security-required product or architecture changes are unresolved.**
+
+### 4E: Marcelo — Testing Strategy
+
+Given the reconciled sections, enrich with: testability assessment; unit/integration/E2E/contract/security/performance/accessibility test strategy; input validation matrix for every accepted input; regression impact; seed data/fixtures/factories/local dev data needs; CI quality gates; manual verification paths; test ownership and issue recommendations. Returns `Testing Strategy` and test work items for Jody.
+
+### 4F: Jody — Planning and Project Creation
+
+Given the full reconciled spec, ask Jody to: convert it into a phased project plan; define phases that map to future implementation PR batches; create ordered, labeled tracker issues (with dependencies, acceptance criteria, owner persona, labels, test obligations) via the issue-tracker skill's `create-issue` operation; create the tracker board with the skill's `create-board` operation; add issues to the board (`add-to-board`) and set Phase/Priority/Owner/Status fields with `set-board-field` (on GitHub these run `gh project` / `gh api graphql`); enrich the spec with project number, issue list, phase order, dependencies, and implementation handoff notes.
+
+Jody's output must be concrete enough that Isabelle can implement each phase using [agent-implementation-workflow.md](agent-implementation-workflow.md).
+
+---
+
+## Phase 5: Tracker Project Mechanics
+
+All project and issue writes go through the issue-tracker skill's contract operations — `create-board`, `create-issue`, `add-to-board`, `set-board-field`, `query-board`. The skill (`.claude/skills/issue-tracker-*/`) carries the backend specifics; the GitHub commands below are what that skill runs on a GitHub project.
+
+On GitHub, check auth and project scope first:
+
+```bash
+gh auth status
+gh auth refresh -h github.com --scopes project   # if project scope is missing
+```
+
+Create the board (`create-board`) and issues (`create-issue` — issue bodies in `tmp/`, GitHub `gh issue create --body-file`), then add each issue to the board (`add-to-board` — GitHub `gh project item-add`). `<OWNER>` is the project owner (user or org).
+
+### 5.1 Required custom fields (MANDATORY — not optional)
+
+Every project created by this workflow **must** carry a `Phase` single-select field. Without it `/implement-project` cannot batch issues into phase-PRs and the plan reverts to a flat "Todo" status that `/implement-issue` has to walk one issue at a time. Skipping this creates weeks of avoidable retrofit work — do not.
+
+**Required fields:**
+
+| Field      | Type          | Options                                                                                          |
+| ---------- | ------------- | ------------------------------------------------------------------------------------------------ |
+| `Phase`    | Single select | `P0: <name>`, `P1: <name>`, `P2: <name>`, … (one per implementation PR; name describes the batch) |
+| `Priority` | Single select | `P0` (must ship), `P1` (should ship), `P2` (nice to have), `P3` (deferred)                        |
+| `Owner`    | Single select | the project's agent personas (e.g. `Isabelle`, `Aaron`, `Otto`, `Bert`, `Melvin`, `Nyx`, `Marcelo`, `Leith`, `Jody`) |
+
+`Status` (created by the tracker by default — `Todo`, `In Progress`, `Done`) is reused as-is; do not duplicate.
+
+**Phase naming rule:** `P<n>: <short batch name>`. The `P<n>` prefix is what `/implement-project` reads to order phases; the short name is for humans. Use `P-1: <name>` for "must happen before P0" prework. Skip-level numbering (`P1.5`) is allowed when a phase is inserted late.
+
+### 5.2 Create the custom fields
+
+The Phase/Priority/Owner fields are part of the `create-board` operation. On GitHub the skill creates each field — prefer `gh project field-create`, fall back to GraphQL:
+
+```bash
+gh project field-create <PROJECT_NUMBER> --owner <OWNER> \
+  --name "Phase" --data-type SINGLE_SELECT \
+  --single-select-options "P0: <name>,P1: <name>,P2: <name>"
+# repeat for Priority and Owner
+```
+
+GraphQL fallback when `gh project field-create` is unavailable: `createProjectV2Field` mutation with `dataType: SINGLE_SELECT` and `singleSelectOptions` (each option needs a `name` and a `color` — valid: `GRAY`, `BLUE`, `GREEN`, `YELLOW`, `ORANGE`, `RED`, `PURPLE`, `PINK`).
+
+### 5.3 Set field values on every issue
+
+Set each item's Phase/Priority/Owner via the skill's `set-board-field` operation. On GitHub: look up field IDs + option IDs once, then `gh project item-edit --id <ITEM> --field-id <FIELD> --project-id <PROJECT> --single-select-option-id <OPTION>` (GraphQL `updateProjectV2ItemFieldValue` is the scripting fallback).
+
+**Verification before declaring Phase 5 complete:** every project item must have a non-null `Phase` AND `Owner` value (the "no empty Phase" rule is part of the contract). Re-query items via `query-board` and assert no item's `Phase` is null; if any are, set them and re-verify. The verification output must be empty.
+
+---
+
+## Phase 6: Sanity Check
+
+Run a fresh general-purpose or planning subagent with **no prior design-loop context**. Give it the final spec path, project number, issue numbers, and the rule: one phase = one implementation PR; each issue = one commit.
+
+Ask it to verify: the spec goal maps to phases and issues; every acceptance criterion has an issue; every security requirement has an issue or explicit AC; every testing requirement has an issue or AC; dependencies are ordered correctly; phase boundaries are implementation-friendly; labels and owners match conventions; no duplicate/missing/vague issues; no hidden work outside the project; **the project has `Phase`, `Priority`, `Owner` fields populated for every item** (re-query via the skill's `query-board` — if any item is missing a `Phase`, the sanity check fails and Jody must fix it before handoff).
+
+Merge sanity-check fixes into the spec. If issues must change, update the tracker immediately.
+
+---
+
+## Phase 7: Reflect and Update Memory
+
+Before reporting back, reflect: did tool choice slow the workflow? Did subagents lack context because prompts were too thin? Did board creation require steps the issue-tracker skill should document (e.g. undocumented `gh`/GraphQL steps on GitHub)? Did any agent disagree in a way future agents should anticipate? Did attachments need a better parsing pattern? Did the spec miss a section until late?
+
+Actions: create/update `docs/agent-lessons/` (PR generalizable lessons back to the engsys lessons-library); update relevant `.claude/agents/*.md` if a role should change; update rules / prompt docs if a behavior should become automatic. Keep memory concise and LLM-optimized: trigger, failure mode, correct behavior, commands/files.
+
+---
+
+## Phase 8: Report Back
+
+Final response to the operator must include: spec path; tracker project link/number; issue list grouped by phase; subagents used and what each contributed; sanity-check result; learning/rule/profile updates made; open questions or decisions needing operator review; explicit request for operator review of the spec/plan before implementation starts. Keep the report short — the spec and project are the durable artifacts.
+
+---
+
+## Spec Quality Checklist
+
+```text
+[ ] Goal and context grounded in repo/docs/attachments
+[ ] Clarifying questions asked in one batch and answered
+[ ] Draft spec created in docs/specs/
+[ ] Leith enriched product/UX
+[ ] Melvin enriched architecture
+[ ] Nyx enriched security/privacy
+[ ] Leith/Melvin revised after Nyx findings if needed
+[ ] Marcelo enriched testing strategy
+[ ] Jody created the phased plan
+[ ] Tracker board created via the issue-tracker skill (create-board)
+[ ] Issues created via the skill (create-issue) with tmp/ body files
+[ ] Issues added to project and organized by phase (add-to-board / set-board-field)
+[ ] Phase / Priority / Owner single-select fields created (5.1, 5.2)
+[ ] Every project item has a non-null Phase value (5.3) — verified via re-query
+[ ] Fresh sanity-check subagent reviewed spec/project/issues
+[ ] Spec updated after sanity check
+[ ] Agent lessons/rules/profiles updated if the workflow revealed reusable lessons
+[ ] Operator received a concise report and review request
+```
+
+---
+
+## Handoff to Implementation
+
+After the operator approves the spec/plan, implementation follows [agent-implementation-workflow.md](agent-implementation-workflow.md) for a single phase or single issue, or [implement-project-workflow.md](implement-project-workflow.md) for an entire project walked phase-by-phase.
+
+Implementation rule: one project phase becomes one PR; every issue in that phase becomes one implementation commit; local review and reflection are required before human handoff. `/implement-project <num>` reads the `Phase` field this workflow created — projects without a populated `Phase` field cannot be auto-implemented and must be retrofitted first (see § 5.1–5.3).