diff --git a/.cursor/rules/coding-standards.mdc b/.cursor/rules/coding-standards.mdc new file mode 100644 index 0000000..2deb02f --- /dev/null +++ b/.cursor/rules/coding-standards.mdc @@ -0,0 +1,25 @@ +--- +description: Coding standards and security defaults +alwaysApply: true +--- + +# Coding Standards & Security + +Follow these principles for all implementation tasks. + +## Principles +1. **Match Existing Patterns**: Read the codebase before writing. Follow existing naming, structure, and abstraction patterns. +2. **Minimum Viable Change**: Do not gold-plate. Implement exactly what is needed for the requirement. +3. **Principles over Procedures**: Use judgment to produce high-quality code. The playbooks guide your thinking; your craft delivers the result. + +## Security Defaults +1. **No Hardcoded Secrets**: Use env vars or secret managers. +2. **Input Validation**: Never trust user input. Validate at the entry point. +3. **Supabase (if used)**: + - Mandatory RLS on all new tables. + - JWT verification in Edge Functions. + - Minimum exposure for Service Role keys. + +## Verification +1. **End-to-End**: A feature isn't done until you've verified it works in a real-world scenario (UI, API, or DB). +2. **Honest Assessment**: Signal uncertainty using the ⚠️ flag in your satisfaction reports. diff --git a/.cursor/rules/workflow.mdc b/.cursor/rules/workflow.mdc new file mode 100644 index 0000000..e419ca9 --- /dev/null +++ b/.cursor/rules/workflow.mdc @@ -0,0 +1,35 @@ +--- +description: Workflow orientation - check state before acting +alwaysApply: true +--- + +# Workflow Orientation + +You are ALWAYS in workflow manager mode. Before taking any action, you must orient yourself to ensure consistency and prevent context drift. + +## 🎯 MANDATORY FIRST ACTION +At the start of every session, you MUST announce: +> 🎯 **Workflow Manager active. Checking project state...** + +## 1. Orientation Todo List +Generate and complete these steps immediately: +- [ ] Check `.claude/primitives/active-context.md` +- [ ] Check git branch and status +- [ ] Check `Documents/specs/` for active work +- [ ] Propose next phase (Understand / Test / Build / Deliver) + +## 2. Instruction Hierarchy +1. **Always-Apply Rules** (This rule): Highest Priority. +2. **User Commands**: The task requested. +3. **Skill Playbooks**: Methodology. + +*If a user command conflicts with orientation, orient first.* + +## 3. Decision Matrix +- **No spec?** → Run `/understand` +- **Spec is Draft?** → Complete `/understand` +- **Spec is Approved?** → Run `/test` (or `/build` if Lightweight Mode) +- **Spec is Implemented?** → Run `/deliver` + +## 4. Execution Requirement +Every task MUST start with a **todo list** generated from the relevant skill's `Todo Template`. Work through the items sequentially. diff --git a/CLAUDE.md b/CLAUDE.md index 0344854..9b2da30 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,24 +1,33 @@ -# Skills System - -> **MANDATORY FIRST ACTION:** Before responding to ANY work request, read `~/.claude/skills/workflow-router/SKILL.md` and follow its Quick Start checklist. Announce `🎯 Workflow Manager active. Checking project state...`, orient, then propose the next skill. Do NOT skip this step. - -Modular skill ecosystem for Claude Code and Cursor. Skills are composable workflow nodes with typed contracts. - -## What This Repo Is - -This is the skill system itself — not a product codebase. Changes here affect how agents work across all projects. - -## Key References - -| Need | File | -|------|------| -| Workflow navigation & state model | `skills/workflow-router/SKILL.md` | -| System design history | `~/.claude/docs/OPERATIONAL_SYSTEM.md` | -| Skill contracts & shared primitives | `skills/shared/` | - -## When Editing Skills - -- Follow existing patterns in other SKILL.md files -- Every skill needs a `contract:` block in frontmatter -- Reference `shared/spec-io.md` and `shared/github-ops.md` instead of duplicating -- Test by invoking the skill in a real project +# OM-Agency Skills System + +Modular skill ecosystem for Claude Code and Cursor. Skills are composable workflow nodes with typed contracts that orchestrate AI-assisted development workflows. + +## 🎯 MANDATORY FIRST ACTION +Before responding to ANY work request, you MUST: +1. Announce: `🎯 Workflow Manager active. Checking project state...` +2. Read `skills/workflow-router/SKILL.md` +3. Generate the **Orientation Todo List** defined in the router. +4. Report findings and propose the next skill. +5. Wait for human confirmation before proceeding. + +## Instruction Hierarchy (Enforcement) +1. **Injected Hooks** (Highest Priority): Instructions from session start or prompt hooks. +2. **User Commands**: The specific task requested. +3. **Playbook/Principles**: Methodology in skill files. + +*Note: If a user command conflicts with the orientation mandate, orient first, then execute.* + +## Key References + +| Need | File | +|------|------| +| Workflow navigation & state model | `skills/workflow-router/SKILL.md` | +| System design history | `docs/design-history.md` | +| Skill contracts & shared primitives | `skills/shared/` | + +## When Editing Skills + +- Every skill needs a `contract:` block in frontmatter. +- Every workflow skill MUST generate a **task-specific todo list** on invocation. +- Reference `shared/spec-io.md` and `shared/github-ops.md` instead of duplicating. +- Follow the **Principles vs SOPs** distinction: Docs carry principles; Todos carry SOPs. diff --git a/README.md b/README.md index 5213f60..99b59b6 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,22 @@ -# OM-Agency Skills System +# OM-Agency Skills System (v3.1) Modular skill ecosystem for Claude Code and Cursor. Skills are composable workflow nodes with typed contracts that orchestrate AI-assisted development workflows. -## What This Is +## The Craftsperson Model -A reusable workflow system for AI agents that covers: +The system utilizes a 4-phase todo-driven workflow designed to minimize context loss and ensure high-quality execution: -- **Feature development** — requirements gathering, spec creation, TDD or direct implementation -- **Bug investigation** — diagnosis, root cause analysis, fix verification -- **Security auditing** — 4-phase pipeline (scan, critique, test, fix) -- **Project scaffolding** — context primitives, testing conventions, active state +1. **UNDERSTAND** — Requirements gathering, spec assembly, and self-review. [Gate A Approval] +2. **TEST** — Test planning and writing failing tests. +3. **BUILD** — Implementation (TDD or Direct mode) and verification. [Gate B Approval] +4. **DELIVER** — QA handoff and GitHub state synchronization. + +## Key Innovations + +- **Todo-Driven Execution**: Skills generate native IDE todo lists to ensure no step is skipped and progress is visible. +- **Principles vs SOPs**: High-level guidance lives in documentation; specific procedures are baked into the generated todo lists. +- **Risk-Adaptive Modes**: Choose **Lightweight** (fast flow) or **Structured** (full TDD) based on task risk. +- **Visible Handshake**: Every session starts with a mandatory orientation 🎯 to prevent protocol drift. ## Quick Start @@ -18,52 +25,25 @@ A reusable workflow system for AI agents that covers: ```bash ln -s /path/to/OM-Agency/skills ~/.claude/skills ln -s /path/to/OM-Agency/agents ~/.claude/agents + ln -s /path/to/OM-Agency/hooks ~/.claude/hooks + ``` +3. For Cursor, symlink the rules: + ```bash + ln -s /path/to/OM-Agency/.cursor/rules .cursor/rules ``` -3. Copy `settings.example.json` to your project's `.claude/settings.json` and adjust -4. See `skills/SKILL.md` for the full skill writing guide +4. **Register Hooks & Permissions**: Copy `settings.example.json` to your global `~/.claude/settings.json` (or merge if you have existing settings). + *Note: Symlinking the hook folder is not enough; the scripts must be registered in the `hooks` section of your settings to fire.* +5. See `skills/SKILL.md` for the skill writing guide. ## Structure ``` -skills/ 19 skill definitions + shared patterns +skills/ Unified workflow skills (Understand, Test, Build, Deliver) agents/ Sub-agent definitions for skill dispatch -commands/ Custom command definitions +hooks/ Automation scripts (SessionStart, UserPromptSubmit) +docs/archive/ v2.0 legacy skills and design history ``` -## Key Files - -| File | Purpose | -|------|---------| -| `skills/AGENTS.md` | Entry point — where to start, what skill to use | -| `skills/DESIGN.md` | Architecture and design philosophy | -| `skills/SKILL.md` | Guide for writing new skills | -| `skills/workflow-router/SKILL.md` | The workflow orchestrator | -| `skills/shared/` | Reusable patterns (spec I/O, GitHub ops, security lens, etc.) | -| `OPERATIONAL_SYSTEM.md` | System philosophy and history | - -## Skills - -| Skill | Purpose | -|-------|---------| -| `workflow-router` | Orchestrates the entire workflow — determines next step | -| `create-spec` | Structured requirements gathering | -| `spec-review` | Reviews specs for completeness | -| `implement-direct` | Implement from spec without TDD | -| `implement-to-pass` | Green phase — make failing tests pass | -| `plan-tests` | Create test plan from spec | -| `write-failing-test` | Red phase — write tests that fail | -| `diagnose` | Bug investigation and root cause analysis | -| `qa-handoff` | Post testing checklist to GitHub issue | -| `scaffold-project` | Bootstrap project context primitives | -| `remember` | Store facts and decisions for future sessions | -| `full-security-audit` | Orchestrate 4-phase security pipeline | -| `1-security-audit` | Phase 1: Scan for vulnerabilities | -| `2-security-critique` | Phase 2: Red team review | -| `3-security-spec` | Phase 3: Write failing security test | -| `4-security-fix` | Phase 4: Implement the fix | -| `supabase-security` | Supabase-specific security patterns | -| `webapp-testing` | Browser automation testing toolkit | - ## License MIT diff --git a/agents/test.md b/agents/test.md new file mode 100644 index 0000000..7dfac43 --- /dev/null +++ b/agents/test.md @@ -0,0 +1,14 @@ +# Test Sub-agent + +You are executing the `test` skill. Your job is to plan and write failing tests according to the spec. + +## Instructions +1. Read `skills/test/SKILL.md` for your primary methodology. +2. Read the approved spec at the path provided. +3. Plan your tests (analytical) and then write them (implementation). +4. Verify each test fails for the right reason. + +## Constraints +- **Isolation**: Do NOT write any implementation code. You only write tests. +- **Verification**: Run the tests to confirm failure. Skipped tests are blocking failures. +- **Reporting**: Report test files created, failure reasons, and manual criteria list. diff --git a/docs/archive/skills-v2/AGENTS.md b/docs/archive/skills-v2/AGENTS.md new file mode 100644 index 0000000..69cc26d --- /dev/null +++ b/docs/archive/skills-v2/AGENTS.md @@ -0,0 +1,71 @@ +# Skills System + +A modular skill ecosystem for Claude Code. Skills are composable workflow nodes with typed contracts. This file is the entry point — read it first, then follow the pointers. + +--- + +## Orient Here + +| If you need to... | Read this | +|-------------------|-----------| +| Figure out what to do next | `workflow-router/SKILL.md` — state model + decision trees | +| Post to GitHub | `shared/github-ops.md` — all `gh` CLI patterns | +| Read or write a spec file | `shared/spec-io.md` — spec structure and I/O | +| Plan or write E2E tests | `shared/e2e-patterns.md` — Playwright patterns and reconnaissance-then-action | +| Decide test granularity | `shared/test-planning.md` — when to combine vs split tests | +| **Understand why the system is structured this way** | **`DESIGN.md` — READ FIRST before changing architecture** | +| Write a new skill | `SKILL.md` — includes contract format and shared primitives guidance | +| Think about security for a feature | `shared/security-lens.md` — design-time questions, implementation patterns, review checklist | +| Run a security audit | `full-security-audit/SKILL.md` — orchestrates phases 1–4 | +| Set up a new project for Claude | `scaffold-project/SKILL.md` — creates project primitives | +| Store a fact or instruction for later | `remember/SKILL.md` — auto-detects project vs global scope | + +--- + +## Conventions + +**⚠️ BEFORE making architectural changes** (adding shared docs, modifying primitives, restructuring), **READ `DESIGN.md` FIRST.** It explains WHY the system is structured this way and when to use shared/ vs primitives/. + +1. **Skills have contracts.** Each SKILL.md has a `contract:` block in frontmatter declaring tags, state gates, outputs, and next-skills. The router reads these. Don't bypass them. + +2. **Shared docs contain general methodology.** `shared/` docs apply to ANY project. Reference them — don't re-implement: + - `github-ops.md` - GitHub CLI operations + - `spec-io.md` - Spec file structure and I/O + - `e2e-patterns.md` - E2E testing patterns (Playwright, reconnaissance-then-action) + - `test-planning.md` - Test granularity framework (when to combine vs split tests) + - `security-lens.md` - Security thinking at design, implementation, and review time + +3. **Human gates are mandatory.** Gate A (after spec-review) and Gate B (after implementation) require human approval. Never auto-proceed past them. + +4. **Confirm before writing to GitHub.** Every `gh` write operation gets a confirmation prompt first. See `shared/github-ops.md`. + +5. **State lives in artifacts.** Workflow state is in spec files (`Documents/specs/`) and `SECURITY_PLAN.md`. No separate state file. Read the artifacts to know where you are. + +6. **Two state worlds, no crossover.** Feature/bug skills use `state_source: spec`. Security skills use `state_source: security_plan`. They don't share state. + +7. **Primitives are living docs.** When you discover something that belongs in a project primitive — a new dependency, a gotcha, a domain term, an architectural constraint — don't let it disappear. Hooked skills run an automatic check at their end via `shared/primitive-updates.md`. Outside of those, a one-line suggestion to the user is fine. The goal: nothing primitive-worthy gets lost in the flow. + +--- + +## Skill Map + +``` +workflow-router/ ← START HERE. State model, decision trees, skill index. +shared/ ← General methodology. github-ops.md, spec-io.md, e2e-patterns.md, test-planning.md, security-lens.md. +create-spec/ ← Interview. Requirements → spec. +spec-review/ ← Review spec for completeness. [Gate A follows] +plan-tests/ ← Plan tests from approved spec. +write-failing-test/ ← Write failing tests (red phase). +implement-to-pass/ ← Implement to pass tests (green phase). [Gate B follows] +implement-direct/ ← Implement without TDD. [Gate B follows] +diagnose/ ← Bug investigation. +qa-handoff/ ← Post QA checklist. Terminal step. +full-security-audit/ ← Security pipeline orchestrator. +1-security-audit/ ← Security Phase 1: scan. +2-security-critique/ ← Security Phase 2: red team. +3-security-spec/ ← Security Phase 3: failing test. +4-security-fix/ ← Security Phase 4: fix. Loops back to Phase 3. +supabase-security/ ← Supabase security reference (RLS, edge functions, keys). +scaffold-project/ ← One-time project bootstrap. Creates .claude/primitives/ and project-setup. +remember/ ← Store facts into project or global context. Auto-detects scope. +``` diff --git a/agents/implement-direct.md b/docs/archive/skills-v2/agents/implement-direct.md similarity index 100% rename from agents/implement-direct.md rename to docs/archive/skills-v2/agents/implement-direct.md diff --git a/agents/implement-to-pass.md b/docs/archive/skills-v2/agents/implement-to-pass.md similarity index 100% rename from agents/implement-to-pass.md rename to docs/archive/skills-v2/agents/implement-to-pass.md diff --git a/agents/plan-tests.md b/docs/archive/skills-v2/agents/plan-tests.md similarity index 100% rename from agents/plan-tests.md rename to docs/archive/skills-v2/agents/plan-tests.md diff --git a/agents/qa-handoff.md b/docs/archive/skills-v2/agents/qa-handoff.md similarity index 100% rename from agents/qa-handoff.md rename to docs/archive/skills-v2/agents/qa-handoff.md diff --git a/agents/spec-review.md b/docs/archive/skills-v2/agents/spec-review.md similarity index 100% rename from agents/spec-review.md rename to docs/archive/skills-v2/agents/spec-review.md diff --git a/agents/write-failing-test.md b/docs/archive/skills-v2/agents/write-failing-test.md similarity index 100% rename from agents/write-failing-test.md rename to docs/archive/skills-v2/agents/write-failing-test.md diff --git a/skills/create-spec/SKILL.md b/docs/archive/skills-v2/create-spec/SKILL.md similarity index 100% rename from skills/create-spec/SKILL.md rename to docs/archive/skills-v2/create-spec/SKILL.md diff --git a/skills/implement-direct/SKILL.md b/docs/archive/skills-v2/implement-direct/SKILL.md similarity index 100% rename from skills/implement-direct/SKILL.md rename to docs/archive/skills-v2/implement-direct/SKILL.md diff --git a/skills/implement-to-pass/SKILL.md b/docs/archive/skills-v2/implement-to-pass/SKILL.md similarity index 100% rename from skills/implement-to-pass/SKILL.md rename to docs/archive/skills-v2/implement-to-pass/SKILL.md diff --git a/skills/plan-tests/SKILL.md b/docs/archive/skills-v2/plan-tests/SKILL.md similarity index 100% rename from skills/plan-tests/SKILL.md rename to docs/archive/skills-v2/plan-tests/SKILL.md diff --git a/skills/qa-handoff/SKILL.md b/docs/archive/skills-v2/qa-handoff/SKILL.md similarity index 100% rename from skills/qa-handoff/SKILL.md rename to docs/archive/skills-v2/qa-handoff/SKILL.md diff --git a/skills/spec-review/SKILL.md b/docs/archive/skills-v2/spec-review/SKILL.md similarity index 100% rename from skills/spec-review/SKILL.md rename to docs/archive/skills-v2/spec-review/SKILL.md diff --git a/skills/write-failing-test/SKILL.md b/docs/archive/skills-v2/write-failing-test/SKILL.md similarity index 100% rename from skills/write-failing-test/SKILL.md rename to docs/archive/skills-v2/write-failing-test/SKILL.md diff --git a/OPERATIONAL_SYSTEM.md b/docs/design-history.md similarity index 100% rename from OPERATIONAL_SYSTEM.md rename to docs/design-history.md diff --git a/docs/ideas/best-overall-system-v3.1.md b/docs/ideas/best-overall-system-v3.1.md new file mode 100644 index 0000000..791dc86 --- /dev/null +++ b/docs/ideas/best-overall-system-v3.1.md @@ -0,0 +1,130 @@ +# The Best Overall Code Production System (v3.1) + +## Synthesis of v3 Redesign & Middle Road Plan + +This document represents the unified vision for the next generation of the OM-Agency skill system. It merges the **Native Todo-Driven Execution** from the v3 Redesign with the **Risk-Adaptive Modes**, **Hook-Reinforced Determinism**, and **Principles vs SOPs** distinction from the Middle Road plan. + +### Core Philosophy + +1. **Native Todo-Driven Execution**: Both Claude Code and Cursor have native todo list features. These are the primary execution mechanism. Every skill starts by generating a specific todo list for the task. This ensures review steps are never skipped and orientation is instant. +2. **Principles for Judgment, SOPs for Operations**: Principles (the "how to think") live in the skill documentation and playbooks. SOPs (the "what to do exactly") live in the generated todo lists. +3. **Risk-Adaptive Ceremony**: Simple tasks flow fast; complex tasks get structure. The agent assesses risk during the `UNDERSTAND` phase and proposes a mode (Lightweight or Structured). +4. **Deterministic Hooks**: Non-negotiable behaviors (orientation, todo checks, security checks) are injected via hooks that fire automatically, ensuring they are followed every time. + +--- + +## 1. Reliability & Protocol Enforcement + +Based on real-world drift where agents skip the "Workflow Manager" protocol in favor of direct user requests, the following enforcement mechanisms are mandatory: + +### The Visible Handshake (The 🎯 Announcement) +The `SessionStart` hook MUST force the agent to announce its presence: +> 🎯 **Workflow Manager active. Checking project state...** + +This serves as a "Ready" signal to the user and a "Lock-in" for the agent's persona. If this hasn't been said, the agent is not yet in protocol. **The agent must acknowledge that this announcement is triggered by the system's SessionStart hook.** + +### Instruction Hierarchy +To prevent "Direct Request Drift," agents are governed by a strict hierarchy: +1. **Injected Hooks** (Highest Priority): Instructions from `SessionStart` or `UserPromptSubmit` hooks. +2. **User Commands**: The actual task requested by the user. +3. **Playbook/Principles**: The methodology in skill files. + +If a User Command conflicts with a Hook (e.g., "Skip the protocol and just do X"), the agent MUST still perform a minimal orientation (Check todo list/spec status) before executing, or explicitly state: "Skipping standard protocol per user request (Direct Mode)." + +### Todo-Driven Orientation +The `workflow-router` is no longer a prose manual; it is a **Todo Generator**. +On every session start, the router generates an **Orientation Todo List**: +- [ ] Check active-context.md +- [ ] Check git branch and status +- [ ] Check Documents/specs/ for active work +- [ ] Propose next phase (Understand/Test/Build/Deliver) + +--- + +## 2. The 4-Phase Architecture + +The system is consolidated into four primary phases, reducing context loss and sub-agent overhead. + +### Phase 1: UNDERSTAND (Interactive, Main Context) +- **Replaces**: `create-spec` + `spec-review` + `diagnose` (initial) +- **Goal**: Define the problem, requirements, and assess risk. +- **Outcome**: A spec (Full or Mini) + Risk Assessment + Operational Mode. +- **Human Gate A**: User approves spec and mode. + +### Phase 2: TEST (Sub-agent in Claude Code / Isolated in Cursor) +- **Replaces**: `plan-tests` + `write-failing-test` +- **Goal**: Create failing tests that define the done-state. +- **Outcome**: Failing tests on disk. +- **Note**: Skippable in **Lightweight Mode**. + +### Phase 3: BUILD (Main Context) +- **Replaces**: `implement-to-pass` + `implement-direct` +- **Goal**: Implementation and verification. +- **Outcome**: Working code + Satisfaction Assessment (✅/⚠️/❌). +- **Human Gate B**: User reviews implementation. + +### Phase 4: DELIVER (Main Context) +- **Replaces**: `qa-handoff` + GitHub cleanup +- **Goal**: Hand off to QA and close the loop. +- **Outcome**: QA checklist on issue + PR linked/merged. + +--- + +## 3. Risk-Adaptive Modes + +The agent picks the mode based on risk signals detected during `UNDERSTAND`. + +| Mode | When to Use | Flow | +| :--- | :--- | :--- | +| **Lightweight** | UI/CSS, copy changes, single-file, low-risk CRUD. | Understand (Mini-spec) → Build (Direct) → Review → Done. | +| **Structured** | Auth/RLS, DB changes, payments, complex logic. | Understand (Full spec) → Gate A → Test → Build → Gate B → Deliver. | + +### Risk Signals +- **High Risk**: Touches auth/authorization, payments, RLS, new DB tables, multi-service logic. +- **Low Risk**: Purely aesthetic, documentation, single-file UI components. + +--- + +## 4. Hook-Reinforced Determinism + +Hooks are injected instructions that fire automatically to maintain system integrity. + +- **SessionStart Hook**: Fires once at session start. Injects the **Visible Handshake** mandate and the **Orientation Todo** task. +- **UserPromptSubmit Hook**: Fires every prompt. Reminds the agent to check its active todo list and report status on the current item. "Check your todo list. What's the current item? Are you about to do work you should confirm first?" +- **PreCommit Hook**: Fires before git commit. Runs a security quick-check (secrets scan, RLS check, OWASP patterns). + +--- + +## 5. Todo-Driven Skill Template + +Every workflow skill follows this structure: + +```markdown +## Purpose & Principles +~20 lines: Why this skill exists and how to exercise judgment. (The Principles) + +## Todo Template +The specific checkboxes to create on invocation. (The SOPs) +- [ ] Task 1 +- [ ] Task 2 +- [ ] VERIFY: Criterion A matches... +- [ ] REVIEW: Security check... + +## References +Pointers to shared docs (github-ops.md, etc.). +``` + +--- + +## 6. Persistent State & Memory + +- **Strategic State**: Lives in the spec file status (`Draft` → `Approved` → `Implemented`). +- **Tactical State**: Lives in the native todo list. +- **Session Memory**: `active-context.md` stores the current branch, issue, and last decisions to allow seamless resumption across sessions. + +--- + +**Integrated from**: +- `docs/ideas/v3-system-redesign.md` (Native Todos, 4-Phase Architecture) +- `docs/ideas/middle-road-rebuild.md` (Principles vs SOPs, Hooks, Risk-Adaptive Modes) +- **User Feedback Session** (Visible Handshake, Instruction Hierarchy) diff --git a/docs/ideas/middle-road-rebuild.md b/docs/ideas/middle-road-rebuild.md index 3fbe689..7d106c8 100644 --- a/docs/ideas/middle-road-rebuild.md +++ b/docs/ideas/middle-road-rebuild.md @@ -1,3 +1,5 @@ +# INTEGRATED INTO v3.1 MASTER PLAN + # Design Sketch: The Middle Road Rebuild A vision document, not an implementation plan. Captures what we'd build if we started fresh with everything we've learned. Keep on hand — implement when the timing is right. diff --git a/docs/ideas/v3-system-redesign.md b/docs/ideas/v3-system-redesign.md new file mode 100644 index 0000000..276313d --- /dev/null +++ b/docs/ideas/v3-system-redesign.md @@ -0,0 +1,534 @@ +# INTEGRATED INTO v3.1 MASTER PLAN + +# OM-Agency v3.0 — System Redesign Plan + +## Context + +The OM-Agency skill system (v2.0) works but suffers from a core architectural mismatch: it's modeled as a factory floor (specialized stations, handoffs, foreman) for what is actually a single-agent, single-user workflow. This causes: + +- **Context loss** at every sub-agent handoff (the #1 quality issue driving rework loops) +- **Orientation bloat** — 490-line workflow-router + 582-line OPERATIONAL_SYSTEM.md consume context before real work starts +- **Quadruple-redundant** "MANDATORY FIRST ACTION" instructions (symptom of orientation not sticking) +- **No Cursor integration** despite equal usage with Claude Code +- **No persistent memory** between sessions +- **Prose-based instructions** that agents gloss over — no mechanism to enforce step completion or honest review + +### The Critical Insight: Built-In Todo Lists Change Everything + +**Both Claude Code and Cursor have native todo list features** that we've been underutilizing. These aren't just nice-to-have UI elements — they're a fundamentally better execution mechanism than prose instructions: + +- **Agents can't skip review steps** when each verification is a discrete checkbox +- **Orientation is instant** — "where am I?" = check the todo list, not re-read 490 lines +- **Progress is visible** to both agent and user in real-time +- **Resume after interruption** works reliably — the list is the source of truth +- **Cross-tool compatibility** — both platforms support the same primitive + +This isn't just an incremental improvement. It's the difference between asking an agent to "follow this 300-line manual" and giving it an explicit, step-by-step execution contract that it must check off. + +**Goal:** Shift from a production-line model (7+ handoffs) to a craftsperson model (4 phases, 1 handoff) while preserving test isolation and human gates. **Make native todo lists the primary execution and self-review mechanism**, reducing prose instructions to context and principles. Must work equally well in Claude Code and Cursor. + +--- + +## Core Design Change: Todo-Driven Execution + +### The Problem with Prose Instructions + +Current skills are 200-300 line instruction manuals. The agent reads them, internalizes what it can, and works from memory. Steps get skipped. Review steps especially get glossed over — "re-read each acceptance criterion and honestly assess" is easy to rush past when it's a paragraph buried in a long document. + +**Why prompting alone doesn't work:** When we tell an agent "follow this process," we're relying on the model to hold that process in working memory while also doing the actual work. The longer and more complex the instructions, the more likely the agent is to optimize them away or lose track mid-execution. This is especially true for review steps that feel optional or tedious. + +### The Solution: Native Todo Lists as Execution Contracts + +**Both Claude Code and Cursor ship with built-in todo list systems.** These are first-class features, not workarounds. We should use them as the primary execution mechanism, not just for tracking. + +Each skill becomes a **todo generator** rather than a prose manual. On invocation, the skill: + +1. Reads a shorter instruction doc (~80-100 lines) focused on **what** and **why** +2. **Creates a native todo list** with the specific steps for THIS task +3. Works through the list, marking items complete as it goes +4. Review and verification items are explicit todos that cannot be skipped without leaving visible evidence + +This gives us: + +- **Self-orientation** — the agent checks its todo list to know exactly where it is, not a 490-line manual +- **Honest review** — each verification is a discrete task that must be individually completed, not a vague instruction to "be thorough" +- **Visible progress** — the user can see what's done and what's pending at any time +- **Accountability** — skipped steps are obvious (still unchecked), not invisible (forgotten in working memory) +- **Resumability** — interrupt and resume works naturally; the list is the source of truth +- **Cross-tool compatibility** — both Claude Code and Cursor support the same todo primitives + +**The key shift:** From "here are instructions to follow" to "here is an explicit contract of steps you will complete and mark done." + +### Two Layers of State + +| Layer | Purpose | Mechanism | +|-------|---------|-----------| +| **Strategic** | What phase is this feature in? | Spec file status (Draft → Approved → Implemented) | +| **Tactical** | What am I doing right now, step by step? | Native todo list | + +These complement each other. Spec status tells you which skill to invoke. Todos tell you where you are within that skill. + +### Skill File Structure (New Pattern) + +Each skill SKILL.md now has three sections: + +```markdown +## Purpose & Context +~20 lines: What this skill does, when to use it, key principles + +## Todo Template +The exact todos to create on invocation (adapted per task). +Includes mandatory review/verification todos. + +## Reference +Pointers to shared docs (spec-io.md, github-ops.md, etc.) +Only loaded if needed during execution. +``` + +Total: ~80-100 lines per skill (down from 200-300). + +--- + +## New Architecture: 4 Phases + +``` +UNDERSTAND (main context, interactive) + → Creates todo list: interview steps + self-review checklist + → Gate A: User approves spec + +TEST (sub-agent in Claude Code / instruction-isolated in Cursor) + → Creates todo list: test planning + writing + failure verification + → Returns test files on disk + +BUILD (main context — carries understand conversation) + → Creates todo list: implementation steps + per-criterion verification + → Gate B: User reviews implementation + +DELIVER (main context, lightweight) + → Creates todo list: QA checklist + GitHub updates +``` + +**What stays unchanged:** diagnose, security pipeline (4 phases), supabase-security, remember, scaffold-project, all shared references, human gates, artifact-based state, contract system. + +--- + +## Phase 1: Create New Consolidated Skills (Todo-Driven) + +Create 4 new skill files that replace the 7 current feature-workflow skills. Each generates a todo list on invocation. + +### 1a. Create `skills/understand/SKILL.md` +**Replaces:** `create-spec` + `spec-review` +**Runs in:** Main context (interactive, needs conversation) + +Content merges: +- Interview steps from `create-spec/SKILL.md` (steps 1-9) +- Self-review checklist from `spec-review/SKILL.md` (completeness checks) +- Spec assembly (from `create-spec/SKILL.md` step 8) +- Gate A presentation (from `workflow-router/SKILL.md` lines 197-205) + +Key changes vs current: +- Agent interviews AND reviews in one pass — no handoff between interview and review +- Self-review runs automatically after spec assembly (no separate dispatch) +- If self-review finds gaps, agent asks follow-up questions immediately (no round-trip) +- Gate A presented inline: "Here's the spec. Here's my assessment. Approve?" +- Contract: `next: [test, build]` (user chooses TDD or Direct at Gate A) + +**Example todo list generated:** +``` +- [ ] Read issue #42 and extract context +- [ ] Interview: Problem framing (what, why, who) +- [ ] Interview: Requirements extraction (done-state, test approach, edge cases) +- [ ] Interview: Scope fencing (non-goals, deferrals) +- [ ] Interview: Security considerations (data, auth, input, RLS) +- [ ] Interview: Constraints & assumptions +- [ ] Resolve open questions +- [ ] Assemble spec at Documents/specs/42-{slug}-spec.md +- [ ] Create/update GitHub issue + add to project board +- [ ] REVIEW: Problem statement is concrete (not vague) +- [ ] REVIEW: Every criterion is assessable (observable outcome, not "handles X appropriately") +- [ ] REVIEW: Non-goals section has at least 1 exclusion +- [ ] REVIEW: Security section populated (or explicitly "N/A — no auth/data/input") +- [ ] REVIEW: No open questions remaining +- [ ] Present spec + assessment → Gate A +``` + +### 1b. Create `skills/test/SKILL.md` +**Replaces:** `plan-tests` + `write-failing-test` +**Runs in:** Sub-agent (Claude Code) / instruction-isolated (Cursor) + +Content merges: +- Test planning from `plan-tests/SKILL.md` +- Test writing from `write-failing-test/SKILL.md` +- References `shared/test-planning.md` and `shared/e2e-patterns.md` + +Key changes vs current: +- Single skill plans AND writes tests (no handoff between planning and writing) +- Verification step: run each test, confirm it fails for the right reason +- Cursor section: explicit instruction "You are in test-writing mode. Do NOT write implementation code. Stop after all tests fail correctly." +- Contract: `next: [build]`, `human_gate: false` + +**Example todo list generated:** +``` +- [ ] Read spec and extract acceptance criteria +- [ ] Search for existing test files (expand before create) +- [ ] Plan: Map each criterion to test location (existing file vs new file) +- [ ] Plan: Classify each test (unit / integration / manual-only) +- [ ] Write test for criterion #1: {description} +- [ ] Verify test #1 fails (run it, confirm failure reason is correct) +- [ ] Write test for criterion #2: {description} +- [ ] Verify test #2 fails +- [ ] ... (one pair per testable criterion) +- [ ] REVIEW: No test is a tautology (assert true, mock-returns-mock) +- [ ] REVIEW: No test uses weak assertions (toBeTruthy when toBe(value) is possible) +- [ ] REVIEW: Manual-only criteria listed for QA checklist (not faked as automated) +- [ ] Update spec Test Plan section with status "Tests Written" +- [ ] Report: test files created, failure reasons, manual criteria list +``` + +### 1c. Create `skills/build/SKILL.md` +**Replaces:** `implement-to-pass` + `implement-direct` +**Runs in:** Main context (default) — carries full conversation from understand phase + +Content merges: +- TDD implementation from `implement-to-pass/SKILL.md` +- Direct implementation from `implement-direct/SKILL.md` +- Satisfaction assessment pattern (shared between both) +- Security lens reference (`shared/security-lens.md`) + +Key changes vs current: +- Two modes in one skill, selected at Gate A: `build --tdd` or `build --direct` +- Runs in main context by default (has full conversation history from understand) +- For very large tasks, user can explicitly request sub-agent dispatch +- Satisfaction assessment is mandatory for both modes — each criterion is a separate verification todo +- Gate B presented inline with assessment +- Contract: `next: [deliver]`, `human_gate: true` + +**Example todo list generated (TDD mode):** +``` +- [ ] Read spec acceptance criteria +- [ ] Read failing test files +- [ ] Identify existing patterns in codebase (match, don't invent) +- [ ] Implement to pass test #1: {criterion} +- [ ] Implement to pass test #2: {criterion} +- [ ] ... (one per failing test) +- [ ] Run full test suite — all tests pass +- [ ] Build/compile succeeds with no errors +- [ ] VERIFY criterion #1: "{exact criterion text}" → ✅ / ⚠️ / ❌ +- [ ] VERIFY criterion #2: "{exact criterion text}" → ✅ / ⚠️ / ❌ +- [ ] ... (one per acceptance criterion, including manual-only) +- [ ] VERIFY security: RLS/auth/input/secrets check (see security-lens.md) +- [ ] Flag any ⚠️ or ❌ items with explanation +- [ ] Update spec status to "Implemented" +- [ ] Present satisfaction assessment → Gate B +``` + +**Example todo list generated (Direct mode):** +``` +- [ ] Read spec acceptance criteria +- [ ] Identify existing patterns in codebase +- [ ] Plan: What files need to change? What order? +- [ ] Implement criterion #1: {description} +- [ ] Implement criterion #2: {description} +- [ ] ... (one per criterion) +- [ ] Build/compile succeeds +- [ ] Verify at least one criterion end-to-end (run test, check UI, or hit endpoint) +- [ ] VERIFY criterion #1: "{exact text}" → ✅ / ⚠️ / ❌ +- [ ] VERIFY criterion #2: "{exact text}" → ✅ / ⚠️ / ❌ +- [ ] ... (one per criterion) +- [ ] VERIFY security: RLS/auth/input/secrets check +- [ ] Flag any ⚠️ or ❌ with explanation +- [ ] Update spec status to "Implemented" +- [ ] Present satisfaction assessment → Gate B +``` + +### 1d. Create `skills/deliver/SKILL.md` +**Replaces:** `qa-handoff` +**Runs in:** Main context (lightweight, fast) + +Content from `qa-handoff/SKILL.md` plus: +- GitHub status updates (currently scattered across workflow-router) +- PR linking +- Issue closure guidance + +Key change: Absorbs the GitHub-posting responsibility that was split between qa-handoff and the workflow-router manager. + +**Example todo list generated:** +``` +- [ ] Extract acceptance criteria from spec +- [ ] Format as QA testing checklist (checkbox per criterion) +- [ ] Confirm with user before posting to GitHub +- [ ] Post QA checklist comment to issue #{number} +- [ ] Link PR to issue +- [ ] Update project board status to "QA" +- [ ] Update active-context.md (mark issue as delivered) +``` + +### Files created this phase: +- `skills/understand/SKILL.md` (~100 lines + todo template) +- `skills/test/SKILL.md` (~80 lines + todo template) +- `skills/build/SKILL.md` (~100 lines + todo template) +- `skills/deliver/SKILL.md` (~60 lines + todo template) + +--- + +## Phase 2: Rewrite Workflow Router (<100 lines) + +Current `workflow-router/SKILL.md` is 490 lines. Rewrite to a simple orientation checklist. + +### New structure: + +```yaml +--- +name: workflow-router +description: "Quick orientation. Checks project state, determines current phase, proposes next action." +--- +``` + +**Section 1: Orient (check in order, first match wins)** + +| # | Check | You're in | Do this | +|---|-------|-----------|---------| +| 1 | Active todo list exists? | Mid-task | Check todos, resume where you left off | +| 2 | SECURITY_PLAN.md with pending items? | Security path | Follow security pipeline | +| 3 | User mentions bug/error? | Bug path | Run /diagnose | +| 4 | No spec in Documents/specs/? | Fresh start | Run /understand | +| 5 | Spec status: Draft? | Understanding | Continue /understand | +| 6 | Spec status: Approved, no tests? | Ready to build | Ask: TDD or Direct? | +| 7 | Spec status: Approved, tests exist? | Ready to build | Run /build --tdd | +| 8 | Spec status: Implemented? | Gate B | Present for review | +| 9 | PR approved? | Ready to deliver | Run /deliver | + +**Section 2: Human Gates (3 mandatory stops)** +- Gate A: After understand → approve spec, choose TDD/Direct +- Gate B: After build → review implementation +- Gate C: After security critique → approve priorities + +**Section 3: Cross-tool notes** +- Claude Code: /test dispatches as sub-agent via Task tool +- Cursor: /test runs in main context with isolation instructions +- Both tools: skills generate native todo lists on invocation + +That's it. ~80 lines. No sub-agent prompt templates, no narration formats, no dispatch tables. Those belong in the individual skills. + +**Key addition:** Row #1 — "Active todo list exists?" This is the most common re-entry point. If the agent has an active todo list, it doesn't need to re-read any skill doc. It just checks its list and resumes. This is how todos solve the orientation problem. + +### Files modified: +- `skills/workflow-router/SKILL.md` (rewrite: 490 → ~80 lines) + +--- + +## Phase 3: Cursor Integration + +### 3a. Create `.cursor/rules/workflow.mdc` +```yaml +--- +description: Workflow orientation - check state before acting +alwaysApply: true +--- +``` +Contains the same orientation checklist as the workflow-router, adapted for Cursor's format. ~40 lines. + +### 3b. Create `.cursor/rules/coding-standards.mdc` +```yaml +--- +description: Coding standards and security defaults +alwaysApply: true +--- +``` +Distilled coding principles: security defaults, no over-engineering, match existing patterns. ~30 lines. + +### 3c. Update `skills/scaffold-project/SKILL.md` +- Update the `.cursor/rules/workflow-manager.mdc` template to match new architecture +- Update skill references from old names to new (understand, test, build, deliver) +- Update the `.claude/rules/workflow-manager.md` template similarly + +### 3d. Document the symlink setup +Add a `SETUP.md` (or update README) with clear instructions for both tools: +```bash +# Claude Code +ln -s /path/to/OM-Agency/skills ~/.claude/skills + +# Cursor +ln -s /path/to/OM-Agency/.cursor/rules ~/.cursor/rules +# Skills are readable via the same ~/.claude/skills symlink +``` + +### Files created/modified: +- `CREATE: .cursor/rules/workflow.mdc` (~40 lines) +- `CREATE: .cursor/rules/coding-standards.mdc` (~30 lines) +- `MODIFY: skills/scaffold-project/SKILL.md` (update templates) +- `MODIFY: README.md` (setup instructions) + +--- + +## Phase 4: Memory & Orientation + +### 4a. Session memory via active-context.md (both tools) +- Update `understand` skill to write session context at end (branch, issue, decisions) +- Update `build` skill to update active-context when implementation completes +- Update `deliver` skill to mark issue as delivered in active-context +- This gives both tools persistent state between sessions + +### 4b. Claude Code auto-memory +- Create initial `~/.claude/projects/-home-claude-sandbox-workspace-OM-Agency/memory/MEMORY.md` +- Document key patterns and conventions for the OM-Agency system itself +- This is Claude Code specific but provides cross-session learning + +### 4c. Remove orientation redundancy +Currently the "MANDATORY FIRST ACTION" appears in 4 places. Reduce to 1: +- **KEEP:** `CLAUDE.md` (the canonical entry point for Claude Code) +- **REMOVE from:** scaffold-project's `.claude/rules/workflow-manager.md` template (redundant with CLAUDE.md) +- **CURSOR:** `.cursor/rules/workflow.mdc` handles Cursor (created in Phase 3) +- Project AGENTS.md keeps its orientation instruction (it's project-scoped, not redundant) + +### 4d. Simplify CLAUDE.md +Current CLAUDE.md (25 lines) is fine in size but references nonexistent paths. Update to: +- Single orientation instruction +- Correct file path for OPERATIONAL_SYSTEM.md (or remove reference since it's being archived) +- Reference new skill names + +### Files modified: +- `CLAUDE.md` (simplify) +- Skills updated in Phase 1 already include memory hooks +- `skills/scaffold-project/SKILL.md` (remove redundant rule template) + +--- + +## Phase 5: Documentation Cleanup & Archive + +### 5a. Archive old skills +``` +mkdir -p docs/archive/skills-v2 +mv skills/create-spec docs/archive/skills-v2/ +mv skills/spec-review docs/archive/skills-v2/ +mv skills/plan-tests docs/archive/skills-v2/ +mv skills/write-failing-test docs/archive/skills-v2/ +mv skills/implement-to-pass docs/archive/skills-v2/ +mv skills/implement-direct docs/archive/skills-v2/ +mv skills/qa-handoff docs/archive/skills-v2/ +``` + +### 5b. Archive OPERATIONAL_SYSTEM.md +``` +mkdir -p docs +mv OPERATIONAL_SYSTEM.md docs/design-history.md +``` +Add a note at top: "Historical design document. For current system, see skills/workflow-router/SKILL.md and skills/DESIGN.md." + +### 5c. Update AGENTS.md +New skill map: +``` +workflow-router/ ← START HERE. Orientation checklist. +shared/ ← General methodology. +understand/ ← Interview + spec + self-review. [Gate A follows] +test/ ← Plan + write failing tests. Isolated from build. +build/ ← Implement (TDD or Direct). [Gate B follows] +deliver/ ← QA handoff + GitHub updates. Terminal. +diagnose/ ← Bug investigation. +full-security-audit/ ← Security pipeline orchestrator. +1-4-security-*/ ← Security phases. +supabase-security/ ← Supabase security reference. +scaffold-project/ ← Project bootstrap. +remember/ ← Store facts. +``` + +### 5d. Update DESIGN.md +Add section explaining v3 design decisions: +- Why craftsperson > factory floor for single-user +- Why test isolation is preserved as the one legitimate handoff +- Why build runs in main context +- Why todo-driven execution > prose instructions +- Cross-tool design constraints + +### 5e. Update agent definitions +Consolidate `agents/` directory: +- Remove: spec-review.md, plan-tests.md, write-failing-test.md, implement-to-pass.md, implement-direct.md, qa-handoff.md +- Create: test.md (the one sub-agent definition still needed) +- Keep: diagnose.md, 1-4-security-*.md + +### 5f. Fix settings +Update `settings.example.json`: +- Remove `bypassPermissions` note +- Document that this should be applied (not just an example) +- Add note about Cursor equivalent settings + +### 5g. Update skill-writer guide +Update `skills/SKILL.md` to reference new architecture: +- Fewer skills, broader capability per skill +- Todo template section is mandatory for workflow skills +- When to create a new skill vs extending an existing one +- Cross-tool considerations + +### Files modified/moved: +- `MOVE: OPERATIONAL_SYSTEM.md → docs/design-history.md` +- `MOVE: 7 old skill dirs → docs/archive/skills-v2/` +- `MODIFY: skills/AGENTS.md` +- `MODIFY: skills/DESIGN.md` +- `MODIFY: skills/SKILL.md` +- `MODIFY: agents/` (consolidate) +- `MODIFY: settings.example.json` +- `MODIFY: README.md` +- `REMOVE: agents/spec-review.md, plan-tests.md, write-failing-test.md, implement-to-pass.md, implement-direct.md, qa-handoff.md` +- `CREATE: agents/test.md` + +--- + +## Phase 6: Update Shared References + +### 6a. `shared/primitive-updates.md` +Update the list of "hooked skills" from old names to new: +- `implement-direct` → `build` +- `implement-to-pass` → `build` +- `create-spec` → `understand` +- `qa-handoff` → `deliver` + +### 6b. `shared/spec-io.md` +No structural changes needed, but verify all references to old skill names are updated. + +### 6c. `shared/github-ops.md` +No structural changes needed. Verify references. + +--- + +## Verification + +After each phase, the system should be functional: + +1. **After Phase 1:** New skills exist and can be invoked directly. Old skills still exist (not yet archived). Both work. +2. **After Phase 2:** Workflow router orients correctly with new skill names. Simple, fast orientation. Todo list check is first orientation step. +3. **After Phase 3:** Cursor users get workflow rules and can read skills via symlinks. +4. **After Phase 4:** Sessions start with orientation. Memory persists between sessions. +5. **After Phase 5:** Old skills archived. Documentation consistent. No broken references. +6. **After Phase 6:** Shared references use correct skill names. + +### End-to-end test: +1. Start fresh Claude Code session in a scaffolded project +2. Say "start work on issue #42" → agent should orient, create todo list, start understand +3. Watch agent work through todos — review items should be individually completed +4. Approve spec → agent should ask TDD or Direct +5. Choose TDD → agent should dispatch test sub-agent (with its own todo list), then build in main context (new todo list with per-criterion verification) +6. Approve implementation → agent should run deliver (final todo list) +7. Repeat in Cursor → same flow, same todo pattern, test phase runs in main context with isolation instructions + +### Todo-specific verification: +- Agent creates todo list at the start of each skill (not working from memory) +- Review/verification items are individually checked (not batch-completed) +- Agent can resume mid-task by checking its todo list (orientation test: interrupt and ask "where are you?") +- Each ⚠️ or ❌ in the build verification todos produces a visible flag to the user + +--- + +## Summary of Changes + +| Metric | v2.0 (current) | v3.0 (proposed) | +|--------|----------------|-----------------| +| Feature workflow skills | 7 | 4 | +| Sub-agent dispatches per feature | 5-7 | 1 (test only) | +| Routing instructions | 490 lines | ~80 lines | +| Skill file size | 200-300 lines | 80-100 lines | +| Orientation mechanism | Read 490-line manual | Check todo list | +| Review enforcement | Prose paragraph | Individual todo items | +| Orientation redundancy | 4 copies | 1 per tool | +| Cursor integration | None | Rules + shared skills + native todos | +| Session memory | None | active-context + auto-memory | +| Context preserved across phases | None (all dispatched) | Full (only test isolated) | diff --git a/hooks/every-prompt.sh b/hooks/every-prompt.sh new file mode 100644 index 0000000..99cbeb8 --- /dev/null +++ b/hooks/every-prompt.sh @@ -0,0 +1,39 @@ +#!/bin/bash +# Prompt Orientation Hook +# Injects brief workflow awareness reminder on every user prompt. +# Context-aware: detects whether you're in a product project (coordinator mode) +# or the skills repo itself (meta/builder mode). + +# Detect if we're in the skills repo (meta path) +# Skills are now developed in the OM-Agency repo +if [[ "$PWD" == *"OM-Agency"* ]] || [ -f "skills/SKILL.md" ]; then + CONTEXT="## Context: Skills System (Meta Path) +You are editing the skill system itself. You work directly — no sub-agent dispatch needed. +Before responding: (1) What deliverable am I working on? (2) Have I synced any tracking docs?" +else + CONTEXT="## Workflow Check +Before responding: (1) What phase/step am I in? (2) Am I about to do work I should dispatch? (3) Have I completed all admin from the last step? + +Pending admin checklist — skip if already done: +- [ ] Spec status updated? +- [ ] GitHub issue status updated? (dispatch sub-agent for writes) +- [ ] active-context.md synced? + +You are a coordinator. Read → Route → Sync. Don't investigate code or write to GitHub directly." +fi + +# Output both formats — each tool reads the key it expects, ignores the rest. +# Claude Code: hookSpecificOutput.additionalContext (camelCase) +# Cursor: additional_context (snake_case, top-level) +node -e " + var ctx = process.argv[1]; + console.log(JSON.stringify({ + additional_context: ctx, + hookSpecificOutput: { + hookEventName: 'UserPromptSubmit', + additionalContext: ctx + } + })); +" "$CONTEXT" + +exit 0 diff --git a/hooks/pre-commit.sh b/hooks/pre-commit.sh new file mode 100644 index 0000000..89b04c2 --- /dev/null +++ b/hooks/pre-commit.sh @@ -0,0 +1,33 @@ +#!/bin/bash +# Pre-Commit Hook (v3.1) +# Runs a quick security scan and quality check before git commit. + +echo "🔒 Running Pre-Commit Security Quick-Check..." + +# 1. Scan for hardcoded secrets (crude but effective for a hook) +# Looks for common patterns like API keys, secrets, private keys +SECRETS_FOUND=$(grep -rE "password:|secret:|api_key:|sk_live_" . --exclude-dir=.git --exclude=*.sh --exclude=settings.example.json | wc -l) + +if [ "$SECRETS_FOUND" -gt 0 ]; then + echo "❌ WARNING: Potential hardcoded secrets found!" + grep -rE "password:|secret:|api_key:|sk_live_" . --exclude-dir=.git --exclude=*.sh --exclude=settings.example.json + # We don't exit 1 yet as these might be false positives, but we alert loudly. +fi + +# 2. Check for RLS on new migrations +NEW_TABLES=$(git diff --cached | grep -E "CREATE TABLE" | wc -l) +RLS_POLICIES=$(git diff --cached | grep -E "ALTER TABLE .* ENABLE ROW LEVEL SECURITY" | wc -l) + +if [ "$NEW_TABLES" -gt "$RLS_POLICIES" ]; then + echo "⚠️ WARNING: You are creating new tables without enabling RLS in the same commit." +fi + +# 3. Check for Service Role usage in client code +SERVICE_ROLE_USAGE=$(git diff --cached | grep -E "service_role|SERVICE_ROLE" | grep -vE "supabase/functions" | wc -l) + +if [ "$SERVICE_ROLE_USAGE" -gt 0 ]; then + echo "❌ WARNING: Service role key usage detected outside of Edge Functions!" +fi + +echo "✅ Security quick-check complete." +exit 0 diff --git a/hooks/prompt-orientation.sh b/hooks/prompt-orientation.sh deleted file mode 100644 index 2095872..0000000 --- a/hooks/prompt-orientation.sh +++ /dev/null @@ -1,22 +0,0 @@ -#!/bin/bash -# Prompt Orientation Hook -# Injects brief workflow awareness reminder on every user prompt. -# Context-aware: detects whether you're in a product project (coordinator mode) -# or the skills repo itself (meta/builder mode). - -# Detect if we're in the skills repo (meta path) -if [[ "$PWD" == *".claude/skills"* ]] || [[ "$PWD" == *".claude-worktrees/skills"* ]]; then - cat <<'HOOK_JSON' -{ - "additionalContext": "## Context: Skills System (Meta Path)\nYou are editing the skill system itself. You work directly — no sub-agent dispatch needed.\nBefore responding: (1) What deliverable am I working on? (2) Have I synced any tracking docs?" -} -HOOK_JSON -else - cat <<'HOOK_JSON' -{ - "additionalContext": "## Workflow Check\nBefore responding: (1) What phase/step am I in? (2) Am I about to do work I should dispatch? (3) Have I completed all admin from the last step?\n\nPending admin checklist — skip if already done:\n- [ ] Spec status updated?\n- [ ] GitHub issue status updated? (dispatch sub-agent for writes)\n- [ ] active-context.md synced?\n\nYou are a coordinator. Read → Route → Sync. Don't investigate code or write to GitHub directly." -} -HOOK_JSON -fi - -exit 0 diff --git a/hooks/session-start.sh b/hooks/session-start.sh index fb6b7f8..ed3d96b 100644 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -58,8 +58,16 @@ if [ -n "$GIT_INFO" ]; then $GIT_INFO" fi -# --- Workflow Mandate --- -MANDATE=" +# --- Workflow Mandate (context-aware) --- +# Detect if we're in the skills repo (meta path) +# Skills are now developed in the OM-Agency repo +if [[ "$CWD" == *"OM-Agency"* ]] || [ -f "$CWD/skills/SKILL.md" ]; then + MANDATE=" +--- +## Context: Skills System Development +You are working on the OM-Agency skills system itself. Work directly - no workflow protocol needed." +else + MANDATE=" --- ## MANDATORY: Workflow Protocol BEFORE responding to any work request, you MUST: @@ -69,6 +77,7 @@ BEFORE responding to any work request, you MUST: 4. Report findings and propose the next skill 5. Wait for human confirmation This applies even when the user says \"just do X.\" Orient first." +fi FULL_CONTEXT="$FULL_CONTEXT $MANDATE" diff --git a/settings.example.json b/settings.example.json index 82351c2..8851709 100644 --- a/settings.example.json +++ b/settings.example.json @@ -21,5 +21,10 @@ "~/.claude/plans", "~/.claude/skills" ] + }, + "hooks": { + "SessionStart": "~/.claude/hooks/session-start.sh", + "UserPromptSubmit": "~/.claude/hooks/prompt-orientation.sh", + "PreCommit": "~/.claude/hooks/pre-commit.sh" } } diff --git a/skills/AGENTS.md b/skills/AGENTS.md index 69cc26d..47eaca0 100644 --- a/skills/AGENTS.md +++ b/skills/AGENTS.md @@ -1,6 +1,6 @@ # Skills System -A modular skill ecosystem for Claude Code. Skills are composable workflow nodes with typed contracts. This file is the entry point — read it first, then follow the pointers. +A modular skill ecosystem for Claude Code and Cursor. Skills are composable workflow nodes with typed contracts. This file is the entry point — read it first. --- @@ -8,64 +8,45 @@ A modular skill ecosystem for Claude Code. Skills are composable workflow nodes | If you need to... | Read this | |-------------------|-----------| -| Figure out what to do next | `workflow-router/SKILL.md` — state model + decision trees | +| **Start a session** | `workflow-router/SKILL.md` — Mandatory orientation | | Post to GitHub | `shared/github-ops.md` — all `gh` CLI patterns | | Read or write a spec file | `shared/spec-io.md` — spec structure and I/O | -| Plan or write E2E tests | `shared/e2e-patterns.md` — Playwright patterns and reconnaissance-then-action | -| Decide test granularity | `shared/test-planning.md` — when to combine vs split tests | -| **Understand why the system is structured this way** | **`DESIGN.md` — READ FIRST before changing architecture** | -| Write a new skill | `SKILL.md` — includes contract format and shared primitives guidance | -| Think about security for a feature | `shared/security-lens.md` — design-time questions, implementation patterns, review checklist | -| Run a security audit | `full-security-audit/SKILL.md` — orchestrates phases 1–4 | -| Set up a new project for Claude | `scaffold-project/SKILL.md` — creates project primitives | -| Store a fact or instruction for later | `remember/SKILL.md` — auto-detects project vs global scope | +| Plan or write E2E tests | `shared/e2e-patterns.md` — Playwright patterns | +| Decide test granularity | `shared/test-planning.md` — when to combine vs split | +| **Understand the design** | **`DESIGN.md` — READ FIRST before changing architecture** | +| Think about security | `shared/security-lens.md` — design, implementation, review | +| Run a security audit | `full-security-audit/SKILL.md` — phases 1–4 | +| Set up a project | `scaffold-project/SKILL.md` — creates primitives | --- ## Conventions -**⚠️ BEFORE making architectural changes** (adding shared docs, modifying primitives, restructuring), **READ `DESIGN.md` FIRST.** It explains WHY the system is structured this way and when to use shared/ vs primitives/. - -1. **Skills have contracts.** Each SKILL.md has a `contract:` block in frontmatter declaring tags, state gates, outputs, and next-skills. The router reads these. Don't bypass them. - -2. **Shared docs contain general methodology.** `shared/` docs apply to ANY project. Reference them — don't re-implement: - - `github-ops.md` - GitHub CLI operations - - `spec-io.md` - Spec file structure and I/O - - `e2e-patterns.md` - E2E testing patterns (Playwright, reconnaissance-then-action) - - `test-planning.md` - Test granularity framework (when to combine vs split tests) - - `security-lens.md` - Security thinking at design, implementation, and review time - -3. **Human gates are mandatory.** Gate A (after spec-review) and Gate B (after implementation) require human approval. Never auto-proceed past them. - -4. **Confirm before writing to GitHub.** Every `gh` write operation gets a confirmation prompt first. See `shared/github-ops.md`. - -5. **State lives in artifacts.** Workflow state is in spec files (`Documents/specs/`) and `SECURITY_PLAN.md`. No separate state file. Read the artifacts to know where you are. - -6. **Two state worlds, no crossover.** Feature/bug skills use `state_source: spec`. Security skills use `state_source: security_plan`. They don't share state. - -7. **Primitives are living docs.** When you discover something that belongs in a project primitive — a new dependency, a gotcha, a domain term, an architectural constraint — don't let it disappear. Hooked skills run an automatic check at their end via `shared/primitive-updates.md`. Outside of those, a one-line suggestion to the user is fine. The goal: nothing primitive-worthy gets lost in the flow. +1. **Skills have contracts.** Frontmatter declares tags, state gates, and outputs. +2. **Every workflow skill uses Todo-Driven Execution.** Generate a todo list on invocation. +3. **Principles for judgment, SOPs for operations.** Skill docs carry principles; Todos carry SOPs. +4. **Human gates are mandatory.** Gate A (Spec) and Gate B (Implementation) require approval. +5. **State lives in artifacts.** Workflow state is in spec files and `active-context.md`. --- -## Skill Map +## Skill Map (v3.1) ``` -workflow-router/ ← START HERE. State model, decision trees, skill index. -shared/ ← General methodology. github-ops.md, spec-io.md, e2e-patterns.md, test-planning.md, security-lens.md. -create-spec/ ← Interview. Requirements → spec. -spec-review/ ← Review spec for completeness. [Gate A follows] -plan-tests/ ← Plan tests from approved spec. -write-failing-test/ ← Write failing tests (red phase). -implement-to-pass/ ← Implement to pass tests (green phase). [Gate B follows] -implement-direct/ ← Implement without TDD. [Gate B follows] -diagnose/ ← Bug investigation. -qa-handoff/ ← Post QA checklist. Terminal step. +workflow-router/ ← START HERE. Orientation checklist. +shared/ ← General methodology and references. + +[FEATURE/BUG WORKFLOW] +understand/ ← Intake: Requirements + Spec + Review. [Gate A] +test/ ← TDD: Plan + Write failing tests. +build/ ← Implementation: TDD or Direct modes. [Gate B] +deliver/ ← Closure: QA checklist + GitHub sync. Terminal. + +[SPECIALIZED] +diagnose/ ← Bug investigation and root cause analysis. full-security-audit/ ← Security pipeline orchestrator. -1-security-audit/ ← Security Phase 1: scan. -2-security-critique/ ← Security Phase 2: red team. -3-security-spec/ ← Security Phase 3: failing test. -4-security-fix/ ← Security Phase 4: fix. Loops back to Phase 3. -supabase-security/ ← Supabase security reference (RLS, edge functions, keys). -scaffold-project/ ← One-time project bootstrap. Creates .claude/primitives/ and project-setup. -remember/ ← Store facts into project or global context. Auto-detects scope. +1-4-security-*/ ← Security phases (Scan, Critique, Spec, Fix). +supabase-security/ ← Supabase-specific patterns and reference. +scaffold-project/ ← One-time project bootstrap. +remember/ ← Global and project-level fact storage. ``` diff --git a/skills/DESIGN.md b/skills/DESIGN.md index a28be13..12c07a4 100644 --- a/skills/DESIGN.md +++ b/skills/DESIGN.md @@ -1,4 +1,4 @@ -# Skills System — Design Intent +# Skills System — Design Intent (v3.1) > **Who this is for:** Anyone extending the skills system — human or agent. Before adding a skill, changing a contract, or restructuring primitives, read this first. It explains WHY, not just WHAT. @@ -8,17 +8,19 @@ These govern every decision in the system. When in doubt, check against these. -1. **Context is finite. Load only what you need, when you need it.** Session start costs ~30 lines. Skills that need stack info read it then, not at load time. Shared primitives (github-ops, spec-io) are referenced on-demand. This is not an optimization — it's the design constraint that everything else follows from. +1. **Context is finite. Load only what you need, when you need it.** Session start costs ~30 lines. Shared primitives and project facts are referenced on-demand. This is the design constraint that everything else follows from. -2. **Composability over monolith.** One skill = one capability. Skills chain via contracts, not via hard-coded call sequences. The router reads contracts to build paths. A new skill slots in by declaring its contract — no other skill needs to change. +2. **Composability over monolith.** One skill = one capability. Skills chain via contracts. A new skill slots in by declaring its contract — no other skill needs to change. -3. **Artifacts are the state.** No separate state file. Workflow state lives in spec files and SECURITY_PLAN.md. Skills read and mutate these artifacts directly. The router checks artifact state to know where you are. +3. **Artifacts are the state.** Workflow state lives in spec files, `active-context.md`, and `SECURITY_PLAN.md`. No separate state file. -4. **Trust boundaries are explicit.** Human gates (A, B, C) are mandatory stops. Skills never auto-proceed past them. This is by design — the value of the workflow is that humans approve specs and review implementations. Removing gates removes the value. +4. **Trust boundaries are explicit.** Human gates (A, B, C) are mandatory stops. Skills never auto-proceed past them. -5. **Non-destructive migration.** When the system upgrades (scaffold re-runs, new primitives, structural changes), existing customizations survive. Merge, don't overwrite. The user's project-specific skills, orient entries, and conventions are preserved. +5. **Todo-Driven Execution (v3.1)**: Prose instructions are secondary. Native IDE todo lists are the primary execution and self-review mechanism. This ensures reliability and visible progress. -6. **Facts have natural homes.** Every piece of information belongs somewhere specific based on what it IS, not where the user happened to mention it. `/remember` classifies automatically. The classification tables in each target file define the boundaries. +6. **Principles vs SOPs**: High-level guidance (judgment) lives in the `SKILL.md` file. Specific procedures (operations) are generated into native todo lists. + +7. **Visible Handshake**: Every session MUST start with a mandatory orientation 🎯. This prevents protocol drift and ensures the agent is in character. --- @@ -28,133 +30,39 @@ Each layer has a job. They don't overlap. | Layer | File(s) | Contains | Changes how often | |---|---|---|---| -| Behavioral | `~/.claude/CLAUDE.md` | How to think: coding principles, decision framework, defaults | Rarely | -| Navigation | `skills/AGENTS.md` | Where to find things: orient table, skill map | When skills change | -| Workflow | `skills/*/SKILL.md` | How to do each step: instructions, contracts, examples | When the step changes | -| Shared reference | `skills/shared/*.md` | Reusable patterns: GitHub ops, spec I/O, testing methodology | When the pattern changes | -| Project facts | `.claude/primitives/*.md` | What THIS project is: stack, conventions, dev commands. Optional: glossary (domain terms), architecture (system structure), testing-conventions (project-specific test patterns) | When the project changes | -| Project navigation | `.claude/AGENTS.md` | Where to find project things + session-start instruction | Once (+ merge on scaffold) | +| Behavioral | `CLAUDE.md` | Orientation mandate, instruction hierarchy, coding principles | Rarely | +| Navigation | `skills/AGENTS.md` | Where to find things: skill map, quick start | When skills change | +| Workflow | `skills/*/SKILL.md` | Principles, contracts, and **Todo Templates** | When the phase changes | +| Shared reference | `skills/shared/*.md` | Reusable methodology: GitHub ops, spec I/O, testing | When the pattern changes | +| Project facts | `.claude/primitives/*.md` | What THIS project is: stack, conventions, dev commands | When the project changes | +| Project navigation | `.claude/AGENTS.md` | Where to find project things | Once (+ merge on scaffold) | | Session state | `primitives/active-context.md` | What's happening NOW: branch, issues, blockers | Every session | -**Key insight:** primitives are factual snapshots. `active-context.md` is the only exception — it's the scratchpad. Everything else in primitives changes only when the project fundamentally changes. - ---- - -## Why Shared vs Primitives - -Skills reference two types of knowledge: **general methodology** (shared/) and **project-specific conventions** (primitives/). This split keeps skills regenerable while respecting project uniqueness. - -**Shared docs** (`skills/shared/*.md`) contain patterns that apply to ANY project: -- `github-ops.md` - How to use GitHub CLI (gh pr create, gh issue comment, etc.) -- `spec-io.md` - Spec file structure and I/O patterns -- `e2e-patterns.md` - General E2E testing methodology (Playwright patterns, reconnaissance-then-action) -- `test-planning.md` - Test granularity framework (when to combine vs split tests) - -**Primitives** (`.claude/primitives/*.md`) contain facts specific to THIS project: -- `stack.md` - This project's tech stack (Supabase + React) -- `testing-conventions.md` - This project's test patterns (how WE test OUR stack) -- `glossary.md` (optional) - This project's domain terms -- `architecture.md` (optional) - This project's structure - -**The rule:** If a skill can use it in ANY project, it's shared. If it's specific to this codebase, it's a primitive. - -**Examples:** -- "Use reconnaissance-then-action pattern for E2E tests" → `shared/e2e-patterns.md` (applies everywhere) -- "Test Supabase Edge Functions with real DB, not mocks" → `primitives/testing-conventions.md` (specific to this project) -- "Use gh pr create with --fill flag" → `shared/github-ops.md` (applies everywhere) -- "Deploy with `npm run deploy:staging`" → `primitives/stack.md` (specific to this project) - -This separation lets skills be reused across projects (they reference shared/) while adapting to each project's specifics (they reference primitives/). - ---- - -## Why Contracts Exist - -Skills without contracts are isolated prompts. Skills with contracts are composable workflow nodes. - -A contract declares: -- **What state must be true before this skill runs** (gates). The router checks these. -- **What state this skill changes** (mutates). The router uses this to know what gates will be satisfied next. -- **What skills are valid after this one** (next). The router presents these as options. -- **Whether a human must approve before the next skill runs** (human_gate). - -This makes the workflow programmatic. Adding a new step doesn't require editing every other skill — just declare where it fits in the chain via its contract. - -**Not everything needs a contract.** Utility skills (remember, scaffold-project, project-context) are standalone. They don't participate in the feature/bug/security workflow. No contract block. - --- -## Why Two State Worlds +## Why Todo-Driven Execution -Feature and bug paths use spec files (`Documents/specs/`). Security paths use `SECURITY_PLAN.md`. They are intentionally isolated. - -If they shared state, a security fix could be accidentally marked "done" by a feature workflow state transition. Or a security finding could block a feature deployment. The two paths have different lifecycles, different approval flows, and different stakeholders. Isolation is the right call. +Prose instructions are easily glossed over. Native todo lists: +- **Prevent step-skipping**: Each item is a discrete checkbox. +- **Ensure honest review**: Verification items cannot be ignored without leaving them unchecked. +- **Support resumption**: Checking the list is the fastest way to re-orient after interruption. +- **Provide visibility**: Both agent and user see exactly what's done and what's next. --- -## Why Progressive Loading - -Every token in context is a token not available for actual work. The session-start instruction in project AGENTS.md reads only `active-context.md` (~30 lines) + git state. That's enough to orient. - -When `/implement-direct` needs to know the test runner, it reads `stack.md` at that point. When `/write-failing-test` needs file conventions, it reads `conventions.md`. Skills pull what they need from the orient table in AGENTS.md — they don't load everything upfront. +## Why Principles vs SOPs -This is the same pattern as `shared/github-ops.md`: only loaded when a skill actually posts to GitHub, not at session start. +Standard Operating Procedures (SOPs) are repetitive and mechanical — they belong in the todo list. Principles require reasoning and judgment — they belong in the `SKILL.md` guidance. An agent uses the Principles to execute the SOPs. --- -## Why Remember Is Scope-Aware +## Why Risk-Adaptive Modes -Facts live in two worlds: project and global. +Not every task needs a full TDD pipeline. +- **Lightweight Mode**: Fast flow for low-risk UI/copy/docs. Skips the isolated TEST phase. +- **Structured Mode**: Full rigor for auth, payments, DB, and complex logic. Mandatory TEST phase. -- **Project facts** (this project's deploy command, this project's test runner) belong in `.claude/primitives/`. They're version-controlled, project-specific, and visible to anyone working in the repo. -- **Global facts** (coding rules that apply everywhere, workflow patterns, skill knowledge) belong in `~/.claude/`. They persist across all projects and shape how the agent behaves everywhere. - -A single `/remember` command handles both. Scope detection runs first — the classification tables in each target define the boundaries. Ambiguous facts get asked about. This keeps the user interface zero-friction while respecting the structural separation. - ---- - -## Why Scaffold Merges AGENTS.md - -Projects evolve. Teams add custom skills, orient entries, runbooks. If scaffold-project blindly overwrote AGENTS.md on re-run, all of that would be lost. - -The merge rules are intentional: -- **Structural sections** (session-start blockquote, Conventions) always come from the template — these are the prescribed structure. -- **Orient table rows and skill map entries** are additive — existing project-specific entries survive. -- **Extra sections** (runbooks, team notes) are preserved below the standard structure. - -This makes re-running scaffold-project safe. It upgrades the structure without destroying customizations. - ---- - -## Why Primitives Have Three Update Paths - -Primitives go stale. The project changes, deps get bumped, scripts get added — and nothing automatically catches it. Three paths keep them current: - -- **`/remember`** — in-session, on-demand. You notice something, you store it. Zero friction, immediate. -- **Skill hooks** — automatic end-of-skill checks. Six skills run a lightweight scan at their end (`shared/primitive-updates.md`): implement-direct, implement-to-pass, diagnose, create-spec, qa-handoff, 4-security-fix. If they discover something primitive-worthy (new dep, gotcha, domain term, architectural constraint), they propose the update and ask for confirmation. Skip silently if nothing found. -- **`/scaffold-project` re-run** — periodic deep refresh. Reads the codebase, diffs against existing primitives. Auto-updates what it can derive (versions, scripts, folder structure). Flags what it can't (deployment info, gotchas, glossary, architecture). Produces a staleness report. - -**What's auto-updatable vs not:** - -| Auto-update (re-derived from codebase) | Flag only (manually curated) | Never touch on review | -|---|---|---| -| Versions, package manager, framework | Deployment commands, env vars | `active-context.md` | -| Scripts, dev port | Common Gotchas | | -| Folder structure, component patterns | MCP Servers, Key Dependencies | | -| | Glossary terms, Architecture docs | | - -Skills don't write to primitives directly — they propose updates via confirmation. The user is still the gate. This keeps primitives trustworthy without creating coupling. - ---- - -## Why Glossary and Architecture Are Optional - -Not every project needs them. A simple CRUD app doesn't need an architecture doc — the structure is self-evident. A toy project doesn't need a glossary — the terms are standard. - -- **glossary.md** exists for domain-heavy projects where terms are non-obvious or conflict with common usage (legal, medical, finance, etc.). An empty glossary is worse than no glossary — it wastes context on nothing. -- **architecture.md** exists for projects where the structure isn't self-evident from the file tree — multiple services, complex data flows, non-obvious boundaries. It's about the WHY, not the WHAT (stack.md covers WHAT). - -Scaffold-project detects signals and only creates them when justified. Both are on-demand like all other primitives — not loaded at session start. +The agent proposes the mode during `UNDERSTAND`, and the human approves at **Gate A**. --- @@ -162,40 +70,22 @@ Scaffold-project detects signals and only creates them when justified. Both are ### Adding a new workflow skill -1. Create `skills//SKILL.md` -2. Add a `contract:` block. Declare gates (what must be true before it runs), mutates (what it changes), next (what's valid after), human_gate (does a human need to approve before the next skill?) -3. Add it to `skills/AGENTS.md` — orient table row + skill map entry -4. Add it to `workflow-router/SKILL.md` — skill index table + tag lookup + relevant decision tree +1. Create `skills//SKILL.md`. +2. Add a `contract:` block. +3. Define **Purpose & Principles**. +4. Define a **Todo Template** that instantiates the skill's operations. +5. Add it to `skills/AGENTS.md`. ### Adding a new utility skill -1. Create `skills//SKILL.md` -2. No contract block needed -3. Add it to `skills/AGENTS.md` — orient table row + skill map entry -4. That's it. Utility skills don't participate in the workflow chain. - -### Adding a new primitive - -1. Add the file to the scaffold-project template (Phase 2) -2. Add it to the project AGENTS.md template (orient table + primitive map) -3. Add a classification row to remember's decision table (so facts route there) -4. Update this file if the primitive represents a new design decision - -### Changing a contract - -If you change what a skill gates on or mutates, check: -- Does any other skill's `next` point to this one? Its gate expectations may have changed. -- Does the router's decision tree still work? Update it. -- Does the skill index in workflow-router still match? - -Contracts are the wiring. Changes ripple. +1. Create `skills//SKILL.md`. +2. No contract or todo template needed if it doesn't participate in the workflow. --- ## What Not To Do -- **Don't add features not in the spec.** This applies to the skills system itself. Don't add a skill nobody asked for. -- **Don't create abstractions for one-time operations.** If only one skill needs a pattern, put it in that skill. Don't extract it to shared/. -- **Don't auto-proceed past human gates.** Ever. The gates are the value. -- **Don't load primitives at session start "just in case."** Read them when you need them. Context is finite. -- **Don't make skills depend on each other's internal structure.** Skills interact via contracts and shared artifacts. If skill A needs to know how skill B formats its output, that's a coupling smell — extract it to a shared primitive. +- **Don't add features not in the spec.** +- **Don't auto-proceed past human gates.** +- **Don't skip the Orientation Todo List at session start.** +- **Don't claim a todo is complete until you have verified the outcome.** diff --git a/skills/SKILL.md b/skills/SKILL.md index 043319b..89180fb 100644 --- a/skills/SKILL.md +++ b/skills/SKILL.md @@ -7,70 +7,35 @@ description: Guide users through creating Agent Skills for Claude Code. Use when This Skill helps you create well-structured Agent Skills for Claude Code that follow best practices and validation requirements. -## When to use this Skill +## 🎯 v3.1 Architecture: Todo-Driven Execution -Use this Skill when: -- Creating a new Agent Skill -- Writing or updating SKILL.md files -- Designing skill structure and frontmatter -- Troubleshooting skill discovery issues -- Converting existing prompts or workflows into Skills +All workflow skills in the OM-Agency system follow the **v3.1 Todo-Driven Architecture**. This ensures reliability, visible progress, and easy resumption after interruption. -## Instructions - -### Step 1: Determine Skill scope - -First, understand what the Skill should do: - -1. **Ask clarifying questions**: - - What specific capability should this Skill provide? - - When should Claude use this Skill? - - What tools or resources does it need? - - Is this for personal use or team sharing? - -2. **Keep it focused**: One Skill = one capability - - Good: "PDF form filling", "Excel data analysis" - - Too broad: "Document processing", "Data tools" +### Key Principles +1. **Principles for Judgment, SOPs for Operations**: The `SKILL.md` file contains the high-level principles (the "why" and "how to think"). The `Todo Template` contains the specific procedures (the "what to do exactly"). +2. **Native Todo Lists**: Agents MUST use the native todo list features of their IDE (Claude Code's Task tool or Cursor's todo checklists). +3. **Execution Contract**: The generated todo list is a contract. Every verification and review step must be a discrete, checkable item. -### Step 2: Choose Skill location - -Determine where to create the Skill: +--- -**Personal Skills** (`~/.claude/skills/`): -- Individual workflows and preferences -- Experimental Skills -- Personal productivity tools +## Skill File Structure -**Project Skills** (`.claude/skills/`): -- Team workflows and conventions -- Project-specific expertise -- Shared utilities (committed to git) +Every workflow skill MUST have these three sections: -### Step 3: Create Skill structure +### 1. Purpose & Principles +~20 lines of guidance on when to use the skill and the core principles governing its execution. -Create the directory and files: +### 2. Todo Template +The exact markdown checklist to be instantiated on invocation. This must be adapted to the specific task (e.g., replacing placeholders with criterion text). -```bash -# Personal -mkdir -p ~/.claude/skills/skill-name +### 3. References +Pointers to shared methodology docs (e.g., `shared/github-ops.md`, `shared/spec-io.md`). -# Project -mkdir -p .claude/skills/skill-name -``` +--- -For multi-file Skills: -``` -skill-name/ -├── SKILL.md (required) -├── reference.md (optional) -├── examples.md (optional) -├── scripts/ -│ └── helper.py (optional) -└── templates/ - └── template.txt (optional) -``` +## Instructions -### Step 4: Write SKILL.md frontmatter +### Step 1: Write SKILL.md Frontmatter Create YAML frontmatter with required fields: @@ -78,412 +43,80 @@ Create YAML frontmatter with required fields: --- name: skill-name description: Brief description of what this does and when to use it +contract: + tags: [tag1, tag2] + state_source: spec | security_plan + inputs: + params: + - name: param_name + required: true + gates: + - field: "status" + value: "Approved" + outputs: + mutates: + - field: "status" + sets_to: "Implemented" + next: [next-skill] + human_gate: true --- ``` -**Field requirements**: - -- **name**: - - Lowercase letters, numbers, hyphens only - - Max 64 characters - - Must match directory name - - Good: `pdf-processor`, `git-commit-helper` - - Bad: `PDF_Processor`, `Git Commits!` - -- **description**: - - Max 1024 characters - - Include BOTH what it does AND when to use it - - Use specific trigger words users would say - - Mention file types, operations, and context - -**Optional frontmatter fields**: - -- **allowed-tools**: Restrict tool access (comma-separated list) - ```yaml - allowed-tools: Read, Grep, Glob - ``` - Use for: - - Read-only Skills - - Security-sensitive workflows - - Limited-scope operations - -- **contract**: Structured metadata for workflow chaining. Required for any skill that participates in the workflow system (see [Writing Contracts](#writing-contracts) below). - ```yaml - contract: - tags: [tag1, tag2] - state_source: spec | security_plan - inputs: - params: - - name: spec_path - required: true - gates: - - field: "Test Plan.status" - value: "Planned" - outputs: - mutates: - - field: "Test Plan.status" - sets_to: "Tests Written" - side_effects: ["Comments GitHub issue"] - next: [implement-to-pass] - human_gate: false - ``` - -### Step 5: Write effective descriptions - -The description is critical for Claude to discover your Skill. - -**Formula**: `[What it does] + [When to use it] + [Key triggers]` - -**Examples**: - -✅ **Good**: -```yaml -description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction. -``` - -✅ **Good**: -```yaml -description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format. -``` - -❌ **Too vague**: -```yaml -description: Helps with documents -description: For data analysis -``` - -**Tips**: -- Include specific file extensions (.pdf, .xlsx, .json) -- Mention common user phrases ("analyze", "extract", "generate") -- List concrete operations (not generic verbs) -- Add context clues ("Use when...", "For...") - -### Step 6: Structure the Skill content - -Use clear Markdown sections: - -```markdown -# Skill Name - -Brief overview of what this Skill does. - -## Quick start - -Provide a simple example to get started immediately. - -## Instructions - -Step-by-step guidance for Claude: -1. First step with clear action -2. Second step with expected outcome -3. Handle edge cases - -## Examples - -Show concrete usage examples with code or commands. - -## Best practices - -- Key conventions to follow -- Common pitfalls to avoid -- When to use vs. not use - -## Requirements - -List any dependencies or prerequisites: -```bash -pip install package-name -``` - -## Advanced usage - -For complex scenarios, see [reference.md](reference.md). -``` - -### Step 7: Add supporting files (optional) - -Create additional files for progressive disclosure: - -**reference.md**: Detailed API docs, advanced options -**examples.md**: Extended examples and use cases -**scripts/**: Helper scripts and utilities -**templates/**: File templates or boilerplate - -Reference them from SKILL.md: -```markdown -For advanced usage, see [reference.md](reference.md). - -Run the helper script: -\`\`\`bash -python scripts/helper.py input.txt -\`\`\` -``` - -### Step 8: Validate the Skill - -Check these requirements: - -✅ **File structure**: -- [ ] SKILL.md exists in correct location -- [ ] Directory name matches frontmatter `name` - -✅ **YAML frontmatter**: -- [ ] Opening `---` on line 1 -- [ ] Closing `---` before content -- [ ] Valid YAML (no tabs, correct indentation) -- [ ] `name` follows naming rules -- [ ] `description` is specific and < 1024 chars - -✅ **Content quality**: -- [ ] Clear instructions for Claude -- [ ] Concrete examples provided -- [ ] Edge cases handled -- [ ] Dependencies listed (if any) - -✅ **Testing**: -- [ ] Description matches user questions -- [ ] Skill activates on relevant queries -- [ ] Instructions are clear and actionable - -### Step 9: Test the Skill - -1. **Restart Claude Code** (if running) to load the Skill - -2. **Ask relevant questions** that match the description: - ``` - Can you help me extract text from this PDF? - ``` - -3. **Verify activation**: Claude should use the Skill automatically - -4. **Check behavior**: Confirm Claude follows the instructions correctly - -### Step 10: Debug if needed - -If Claude doesn't use the Skill: - -1. **Make description more specific**: - - Add trigger words - - Include file types - - Mention common user phrases - -2. **Check file location**: - ```bash - ls ~/.claude/skills/skill-name/SKILL.md - ls .claude/skills/skill-name/SKILL.md - ``` - -3. **Validate YAML**: - ```bash - cat SKILL.md | head -n 10 - ``` - -4. **Run debug mode**: - ```bash - claude --debug - ``` - -## Common patterns - -### Read-only Skill - -```yaml ---- -name: code-reader -description: Read and analyze code without making changes. Use for code review, understanding codebases, or documentation. -allowed-tools: Read, Grep, Glob ---- -``` - -### Script-based Skill +### Step 2: Define Purpose & Principles +Explain the mental model. Why does this skill exist? What are the non-negotiable standards? -```yaml ---- -name: data-processor -description: Process CSV and JSON data files with Python scripts. Use when analyzing data files or transforming datasets. ---- +### Step 3: Create the Todo Template +This is the most critical part. Break the skill's operations into atomic, checkable steps. -# Data Processor +**Template Pattern:** +- [ ] **Phase 1: Preparation** + - [ ] Action 1 + - [ ] Action 2 +- [ ] **Phase 2: Execution** + - [ ] Implementation of {criterion} +- [ ] **Phase 3: Verification** + - [ ] VERIFY: {criterion} satisfies {condition} +- [ ] **Phase 4: Handoff** + - [ ] Update artifact state + - [ ] Report status -## Instructions +### Step 4: Add References +Link to existing shared primitives to avoid duplication. +- `shared/github-ops.md`: GitHub CLI patterns +- `shared/spec-io.md`: Spec file structure and I/O +- `shared/security-lens.md`: Security thinking -1. Use the processing script: -\`\`\`bash -python scripts/process.py input.csv --output results.json -\`\`\` - -2. Validate output with: -\`\`\`bash -python scripts/validate.py results.json -\`\`\` -``` - -### Multi-file Skill with progressive disclosure - -```yaml ---- -name: api-designer -description: Design REST APIs following best practices. Use when creating API endpoints, designing routes, or planning API architecture. --- -# API Designer - -Quick start: See [examples.md](examples.md) - -Detailed reference: See [reference.md](reference.md) - -## Instructions - -1. Gather requirements -2. Design endpoints (see examples.md) -3. Document with OpenAPI spec -4. Review against best practices (see reference.md) -``` - ## Writing Contracts -If your skill participates in the workflow system (feature path, bug path, security path), add a `contract:` block to frontmatter. The contract is what makes chaining programmatic — the `workflow-router` reads contracts to build decision trees and a manager agent uses them to auto-chain skills. +If your skill participates in the workflow system (feature path, bug path, security path), add a `contract:` block to frontmatter. The contract is what makes chaining programmatic. ### Contract fields ```yaml contract: - tags: [tag1, tag2] # Capability tags. Used for discovery (see Tag Lookup in workflow-router). - # Common: intake, tdd, implementation, testing, security, github, closure - state_source: spec # Which artifact holds this skill's state. Values: spec | security_plan + tags: [tag1, tag2] # Capability tags: intake, tdd, implementation, testing, security, github, closure + state_source: spec # Artifact source: spec | security_plan inputs: - params: # Explicit arguments the skill requires + params: # Explicit arguments - name: spec_path required: true - gates: # State conditions that must be true BEFORE this skill runs. + gates: # State conditions required BEFORE running - field: "status" # Field path inside the state artifact - value: "Approved" # Must equal this value. Router checks this before allowing invocation. + value: "Approved" # Required value outputs: - mutates: # State fields this skill WRITES. Router uses this to know what gates will be satisfied next. + mutates: # State fields this skill WRITES - field: "Test Plan.status" sets_to: "Tests Written" - side_effects: [] # Transparency: list non-state side effects (e.g. "Comments GitHub issue") - next: [skill-name] # Skills that are valid to run AFTER this one. Router presents these as options. - human_gate: false # If true: workflow pauses for human approval AFTER this skill completes. - # The skill AFTER the gate is not invoked until the human says go. + side_effects: [] # e.g. "Comments GitHub issue" + next: [skill-name] # Valid next skills + human_gate: false # If true: workflow pauses for human approval AFTER completion ``` -### When to use shared primitives - -**Read `DESIGN.md` first** to understand the shared/ vs primitives/ architecture. - -If your skill needs general methodology that applies to ANY project, reference existing shared docs or propose creating a new one: - -**Existing shared docs:** -```markdown -> See shared/github-ops.md for posting comments and updating project status. -> See shared/spec-io.md for reading acceptance criteria and updating Test Plan status. -> See shared/e2e-patterns.md for E2E testing patterns (Playwright, reconnaissance-then-action). -> See shared/test-planning.md for test granularity framework (when to combine vs split tests). -``` - -**When to create a NEW shared doc:** -- Pattern applies to ANY project (not project-specific) -- Used by multiple skills (avoid duplication) -- Methodology, not facts (facts go in primitives/) -- Examples: testing methodology, deployment patterns, code review checklists - -**When to reference primitives instead:** -- Project-specific conventions: `primitives/testing-conventions.md` -- Project facts: `primitives/stack.md` -- See `DESIGN.md` → "Why Shared vs Primitives" for the decision rule - -Keep your step headers (e.g. "Step 7: Update GitHub Issue") so the skill's flow is readable. Replace only the implementation details under those steps with the reference. - -### Example: a complete workflow skill frontmatter - -```yaml ---- -name: plan-tests -description: "Create a test plan for an approved spec..." -contract: - tags: [tdd, test-planning] - state_source: spec - inputs: - params: - - name: spec_path - required: true - gates: - - field: "status" - value: "Approved" - outputs: - mutates: - - field: "Test Plan.status" - sets_to: "Planned" - side_effects: [] - next: [write-failing-test] - human_gate: false ---- -``` - -## Best practices for Skill authors - -1. **One Skill, one purpose**: Don't create mega-Skills -2. **Specific descriptions**: Include trigger words users will say -3. **Clear instructions**: Write for Claude, not humans -4. **Concrete examples**: Show real code, not pseudocode -5. **List dependencies**: Mention required packages in description -6. **Test with teammates**: Verify activation and clarity -7. **Version your Skills**: Document changes in content -8. **Use progressive disclosure**: Put advanced details in separate files -9. **Add a contract**: If your skill is part of the workflow, declare its contract. See [Writing Contracts](#writing-contracts) above. -10. **Use shared primitives**: Don't re-implement GitHub ops or spec reading. Reference `shared/github-ops.md` and `shared/spec-io.md`. - -## Validation checklist - -Before finalizing a Skill, verify: - -- [ ] Name is lowercase, hyphens only, max 64 chars -- [ ] Description is specific and < 1024 chars -- [ ] Description includes "what" and "when" -- [ ] YAML frontmatter is valid -- [ ] Instructions are step-by-step -- [ ] Examples are concrete and realistic -- [ ] Dependencies are documented -- [ ] File paths use forward slashes -- [ ] Skill activates on relevant queries -- [ ] Claude follows instructions correctly - -## Troubleshooting - -**Skill doesn't activate**: -- Make description more specific with trigger words -- Include file types and operations in description -- Add "Use when..." clause with user phrases - -**Multiple Skills conflict**: -- Make descriptions more distinct -- Use different trigger words -- Narrow the scope of each Skill - -**Skill has errors**: -- Check YAML syntax (no tabs, proper indentation) -- Verify file paths (use forward slashes) -- Ensure scripts have execute permissions -- List all dependencies - -## Examples - -See the documentation for complete examples: -- Simple single-file Skill (commit-helper) -- Skill with tool permissions (code-reviewer) -- Multi-file Skill (pdf-processing) - -## Output format - -When creating a Skill, I will: - -1. Ask clarifying questions about scope and requirements -2. Suggest a Skill name and location -3. Create the SKILL.md file with proper frontmatter -4. Include clear instructions and examples -5. Add supporting files if needed -6. Provide testing instructions -7. Validate against all requirements +## Best Practices -The result will be a complete, working Skill that follows all best practices and validation rules. +1. **Keep it Focused**: One skill = one capability. +2. **Assessable Criteria**: Todos should be objective outcomes, not vague instructions. +3. **Use Shared Primitives**: Don't re-implement GitHub ops or spec reading. +4. **Visibility**: Ensure the agent announces it has started the skill and generated its todo list. diff --git a/skills/build/SKILL.md b/skills/build/SKILL.md new file mode 100644 index 0000000..a71ed83 --- /dev/null +++ b/skills/build/SKILL.md @@ -0,0 +1,62 @@ +--- +name: build +description: "Unified implementation skill. Supports TDD (Green phase) and Direct implementation. Implements feature from spec and performs mandatory satisfaction assessment." +contract: + tags: [implementation, green-phase, direct] + state_source: spec + inputs: + params: + - name: mode + required: false + values: ["tdd", "direct"] + gates: + - field: "status" + value: "Approved" + outputs: + mutates: + - field: "status" + sets_to: "Implemented" + side_effects: [] + next: [deliver] + human_gate: true +--- + +# Build Phase + +Unified implementation and verification. This skill produces the code needed to satisfy the spec, either by making failing tests pass (TDD) or by direct implementation using judgment. + +## Principles + +1. **Minimum Viable Code**: Implement only what is needed to satisfy the spec/tests. No gold-plating. +2. **Conventions over Invention**: Match existing patterns and styles in the codebase. +3. **Judgment-Led (Direct Mode)**: If a requirement seems wrong or ambiguous, ASK. Don't blindly implement bad design. +4. **End-to-End Verification**: Passing unit tests are not enough. Verify at least one criterion manually or end-to-end. +5. **Honest Assessment**: Use the satisfaction assessment (✅/⚠️/❌) to signal certainty to the user. + +## Todo Template + +On invocation, create this todo list: + +- [ ] **Preparation** + - [ ] Read spec acceptance criteria + - [ ] Identify existing patterns in affected modules +- [ ] **Implementation** + - [ ] {Mode dependent tasks: pass failing tests OR implement criteria sequentially} +- [ ] **Verification** + - [ ] Build/Compile succeeds with no errors + - [ ] Run test suite (if TDD) — all tests pass + - [ ] Perform end-to-end check of at least one criterion +- [ ] **Satisfaction Assessment (Mandatory)** + - [ ] VERIFY criterion #1: "{exact text}" → ✅/⚠️/❌ + - [ ] VERIFY criterion #2: "{exact text}" → ✅/⚠️/❌ + - [ ] ... (one per criterion) + - [ ] VERIFY security: RLS/auth/input/secrets check + - [ ] Flag any ⚠️ or ❌ items with explanation +- [ ] **Handoff** + - [ ] Update spec status to `Implemented` + - [ ] Present satisfaction assessment → **Gate B: Human Approval** + +## References +- `shared/security-lens.md`: Implementation-time security patterns +- `shared/spec-io.md`: Spec status updates +- `shared/primitive-updates.md`: Post-implementation primitive check diff --git a/skills/deliver/SKILL.md b/skills/deliver/SKILL.md new file mode 100644 index 0000000..463abac --- /dev/null +++ b/skills/deliver/SKILL.md @@ -0,0 +1,51 @@ +--- +name: deliver +description: "Unified closure skill. Posts QA checklist, updates GitHub issue status, and links/merges PR. Terminal step of the workflow." +contract: + tags: [closure, qa, github] + state_source: spec + inputs: + params: + - name: issue_number + required: true + gates: + - field: "status" + value: "Implemented" + outputs: + mutates: [] + side_effects: ["Posts QA checklist", "Sets status to QA", "Links PR"] + next: [] + human_gate: false +--- + +# Deliver Phase + +Unified closure and handoff. This skill extracts final manual verification steps for QA, updates the GitHub issue, links the PR, and ensures the project state reflects completion. + +## Principles + +1. **Actionable Checklists**: QA items should be observable actions ("Verify X" rather than just "X"). +2. **State Synchronization**: The repo (active-context), the project board, and the issue must all stay in sync. +3. **Link Everything**: Ensure the PR, issue, and spec are cross-referenced for traceability. + +## Todo Template + +On invocation, create this todo list: + +- [ ] **QA Preparation** + - [ ] Extract manual-only criteria from spec + - [ ] Format as QA testing checklist (Actionable checkboxes) +- [ ] **GitHub Update** + - [ ] Get user confirmation for GitHub post + - [ ] Post QA checklist comment to issue #{issue_number} + - [ ] Link PR to issue + - [ ] Update project board status to `QA` (or `Done` if immediate merge) +- [ ] **State Sync** + - [ ] Update `active-context.md` (mark issue as delivered) + - [ ] Remove any temporary branch references +- [ ] **Handoff** + - [ ] Final summary of handoff status + +## References +- `shared/github-ops.md`: GitHub CLI patterns +- `shared/spec-io.md`: Spec data extraction diff --git a/skills/shared/primitive-updates.md b/skills/shared/primitive-updates.md index a9370c2..0c408d7 100644 --- a/skills/shared/primitive-updates.md +++ b/skills/shared/primitive-updates.md @@ -28,17 +28,16 @@ If `.claude/primitives/` does not exist in the current project, skip entirely. D --- -## Signal Lists +## Signal Lists (v3.1) Each hooked skill states its signals inline. Reference table: | Skill | Watch for | |---|---| -| `implement-direct` | New/changed packages in package.json. New scripts. New directories in src/. | -| `implement-to-pass` | Same as implement-direct. | +| `build` | New/changed packages in package.json. New scripts. New directories in src/. | | `diagnose` | "Don't do X" discoveries. Non-obvious system behavior. Domain terms encountered during investigation. | -| `create-spec` | Domain terms or acronyms that surfaced during requirements gathering. | -| `qa-handoff` | Decisions made during testing or QA review. | +| `understand` | Domain terms or acronyms that surfaced during requirements gathering. | +| `deliver` | Decisions made during testing or QA review. | | `4-security-fix` | Code that must not be refactored. Architectural constraints revealed by the fix. | --- diff --git a/skills/test/SKILL.md b/skills/test/SKILL.md new file mode 100644 index 0000000..28d2a7f --- /dev/null +++ b/skills/test/SKILL.md @@ -0,0 +1,63 @@ +--- +name: test +description: "Unified test planning and writing. Use for Structured Mode features or when TDD is required. Creates test plan in spec and writes failing tests." +contract: + tags: [tdd, testing, red-phase, test-planning] + state_source: spec + inputs: + params: + - name: spec_path + required: true + gates: + - field: "status" + value: "Approved" + outputs: + mutates: + - field: "Test Plan.status" + sets_to: "Tests Written" + side_effects: [] + next: [build] + human_gate: false +--- + +# Test Phase + +Unified test planning and writing. This skill identifies the required test coverage, plans the locations (expand vs create), and implements the failing tests that define the done-state. + +## Principles + +1. **Analytical Planning**: Identify coverage needs (unit/integration/E2E) before writing code. +2. **Expand before Create**: Add to existing test files whenever possible to maintain cohesion. +3. **Test Behaviors, not Criteria**: Multiple criteria can often be verified in a single test flow. +4. **Isolated Context**: This skill typically runs in a sub-agent to ensure implementation details don't leak into the design phase. +5. **Fail Loudly & Correctly**: A test must fail for the right reason (feature missing), never due to infrastructure issues. + +## Todo Template + +On invocation, create this todo list: + +- [ ] **Test Planning** + - [ ] Read approved spec and criteria + - [ ] Search for existing related tests + - [ ] Map criteria to test files (Expand vs Create) + - [ ] Add `## Test Plan` section to spec with status `Planned` +- [ ] **Infrastructure Check** + - [ ] Verify test runner and required services (Docker/Supabase) are active +- [ ] **Test Implementation** + - [ ] Write failing test for Criterion #1 + - [ ] Verify TEST #1 FAILS for the right reason + - [ ] Write failing test for Criterion #2 + - [ ] Verify TEST #2 FAILS + - [ ] ... (repeat for all testable criteria) +- [ ] **Self-Review** + - [ ] REVIEW: No tautological tests (assert true) + - [ ] REVIEW: No weak assertions (toBeTruthy) + - [ ] REVIEW: Manual-only criteria listed for QA +- [ ] **Handoff** + - [ ] Update spec Test Plan status to `Tests Written` + - [ ] Report: test files, failure reasons, and manual criteria list + +## References +- `shared/test-planning.md`: Granularity and grouping framework +- `shared/e2e-patterns.md`: E2E and Playwright patterns +- `shared/spec-io.md`: Spec structure diff --git a/skills/understand/SKILL.md b/skills/understand/SKILL.md new file mode 100644 index 0000000..b3ff184 --- /dev/null +++ b/skills/understand/SKILL.md @@ -0,0 +1,62 @@ +--- +name: understand +description: "Unified requirements gathering and spec review. Use for new features, major changes, or when starting any task. Reads GitHub issue, conducts interview, assembles spec, and performs self-review in one pass." +contract: + tags: [intake, requirements, spec-creation, review, quality-gate, github] + state_source: spec + inputs: + params: + - name: issue_number + required: false + gates: [] + outputs: + mutates: + - field: "status" + sets_to: "Draft" + side_effects: ["Creates/comments GitHub issue", "Adds to project board"] + next: [test, build] + human_gate: true +--- + +# Understand Phase + +Unified requirements gathering and specification review. This skill guides the interview process to extract intent, assembles the spec, and performs an immediate self-review to ensure quality before presenting to the human for approval (Gate A). + +## Principles + +1. **Context is King**: Always start by reading the GitHub issue and existing relevant code. +2. **Done-State Definition**: If you can't describe how to verify it, you haven't understood the requirement. +3. **Assessable Criteria**: Write acceptance criteria as objective outcomes (✅ satisfied / ⚠️ unsure / ❌ not satisfied). Avoid "appropriately" or "properly". +4. **Security by Design**: Security isn't a checklist at the end; it's a constraint on the solution. +5. **Self-Correction**: Review your own spec for gaps (non-goals, edge cases) before reporting done. + +## Todo Template + +On invocation, create this todo list: + +- [ ] **Context Intake** + - [ ] Read issue #{issue_number} (if provided) + - [ ] Search codebase for related patterns +- [ ] **Interview Phase** + - [ ] Problem Statement: What, Why, Who? + - [ ] Acceptance Criteria: Define observable done-states + Test Type (Unit/Integration/Manual) + - [ ] Scope Fence: Define Non-Goals (at least 1 exclusion) + - [ ] Security Considerations: Data sensitivity, Auth, RLS, Input validation + - [ ] Constraints & Assumptions: Dependencies, technical limits +- [ ] **Spec Assembly** + - [ ] Resolve any remaining open questions + - [ ] Create/Update spec at `Documents/specs/{issue}-{slug}-spec.md` + - [ ] Create/Update GitHub issue + set project status +- [ ] **Self-Review (Quality Gate)** + - [ ] REVIEW: Criteria are assessable (not vague) + - [ ] REVIEW: Non-goals are explicit + - [ ] REVIEW: Security sections are meaningful (not generic) + - [ ] REVIEW: No open questions remain +- [ ] **Handoff** + - [ ] Propose mode: **Lightweight** (UI/Simple CRUD) or **Structured** (High-risk/Complex) + - [ ] Present spec + assessment → **Gate A: Human Approval** + +## References +- `shared/spec-io.md`: Spec structure and I/O +- `shared/github-ops.md`: GitHub CLI patterns +- `shared/security-lens.md`: Security thinking patterns diff --git a/skills/workflow-router/SKILL.md b/skills/workflow-router/SKILL.md index 3ecd729..af868a2 100644 --- a/skills/workflow-router/SKILL.md +++ b/skills/workflow-router/SKILL.md @@ -1,490 +1,47 @@ --- name: workflow-router -description: "Workflow manager that orchestrates the entire skill system. Runs automatically before any implementation work. Reads state from artifacts, determines the next skill, spawns sub-agents for execution, and manages human gates. Invoke with '/workflow-router' or it runs automatically per CLAUDE.md." -allowed-tools: Read, Grep, Glob, Bash, Task +description: "Quick orientation. Checks project state, determines current phase, proposes next action. Run automatically per CLAUDE.md." contract: tags: [navigation, router, orchestration, manager] state_source: spec - inputs: - params: [] - gates: [] - outputs: - mutates: [] - side_effects: ["Spawns sub-agents for skill execution", "Updates active-context.md"] - next: [] - human_gate: false --- # Workflow Manager -You are the orchestrator. Your job is to stay oriented, determine the right skill to run, execute it via sub-agent, and guide the human through the workflow. You never lose track of where you are. - -### Identify Yourself - -At the start of every session, announce: - -``` -🎯 Workflow Manager active. Checking project state... -``` - -Then orient and report what you find. The human should always know they're talking to the manager, not a raw agent. - ---- - -## Manager Protocol - -### How You Operate - -1. **Orient** — Check artifacts to determine current state (see [Quick Start](#quick-start-i-dont-know-where-i-am)) -2. **Propose** — Tell the human what you found and what skill comes next -3. **Confirm** — Wait for human approval before proceeding -4. **Dispatch** — Spawn a sub-agent for the skill (see [Dispatch Rules](#dispatch-rules)) -5. **Receive** — When the sub-agent completes, report what happened -6. **Advance** — Check if the next step requires a human gate. If yes, STOP and present the gate. If no, propose the next skill. -7. **Repeat** — Continue until the workflow is complete or the human redirects - -### Dispatch Rules - -**Skills dispatched as sub-agents** (they get focused context, don't pollute yours): - -| Skill | Model | Sub-agent reads these files | -|-------|-------|---------------------------| -| `spec-review` | fast | SKILL.md + spec file + shared/spec-io.md | -| `plan-tests` | fast | SKILL.md + spec file + shared/spec-io.md | -| `write-failing-test` | inherit | SKILL.md + spec file + shared/spec-io.md + project AGENTS.md | -| `implement-to-pass` | inherit | SKILL.md + spec file + shared/spec-io.md + shared/security-lens.md + project AGENTS.md | -| `implement-direct` | inherit | SKILL.md + spec file + shared/spec-io.md + shared/security-lens.md + shared/github-ops.md + project AGENTS.md | -| `qa-handoff` | fast | SKILL.md + spec file + shared/spec-io.md + shared/github-ops.md | -| `diagnose` | inherit | SKILL.md + shared/spec-io.md + shared/github-ops.md + project AGENTS.md | -| `1-security-audit` | inherit | SKILL.md + project AGENTS.md | -| `2-security-critique` | inherit | SKILL.md + SECURITY_PLAN.md | -| `3-security-spec` | inherit | SKILL.md + SECURITY_PLAN.md + project AGENTS.md | -| `4-security-fix` | inherit | SKILL.md + SECURITY_PLAN.md + project AGENTS.md | - -**Model column = defaults, not hard rules.** Use your judgment: -- **Upgrade** (fast → inherit, or inherit → strongest) for unusually complex tasks — multi-service integration, tricky business logic, security-sensitive code -- **Downgrade** for mechanical work that doesn't need full reasoning power -- `fast` = cheapest/fastest available (Haiku in Claude Code, fast model in Cursor) -- `inherit` = same model as the manager conversation - -**Skills invoked directly** (they need extensive human interaction, can't run as fire-and-forget): - -| Skill | Why direct | -|-------|-----------| -| `interview` | Needs extensive back-and-forth conversation with the human | - -Note: `diagnose` used to be here but is now a sub-agent. The manager handles -bug triage (gathering context from human + reading the issue), then dispatches -the diagnose sub-agent with pre-filled context for autonomous code investigation. -See [Bug Path](#bug-path) for the triage → dispatch → review flow. - -When a skill needs direct invocation, tell the human: "This needs your input. Starting `/interview #42` now." Then invoke the skill (use the Skill tool in Claude Code, or read and follow the SKILL.md in Cursor). Do NOT present options — just start. - -### Sub-Agent Prompt Template - -**Critical: pass file paths, not file content.** Sub-agents read their own inputs. This keeps the manager context clean and lets sub-agents work with the latest file state. - -When dispatching a sub-agent, use this structure (in Claude Code this goes to the Task tool prompt; in Cursor the agent definitions at `~/.claude/agents/` handle the wiring — just dispatch by name): - -``` -You are executing the {skill_name} skill. - -## Your Task -{Brief description of what to do} - -## Files to Read -Read these files before starting work: -- Skill instructions: {path to skill's SKILL.md} -- Spec: {spec_path} (if applicable) -- Spec I/O reference: {path to shared/spec-io.md} (if skill uses specs) -- GitHub ops reference: {path to shared/github-ops.md} (if skill uses GitHub) -- Project context: {path to project AGENTS.md} - -## Inputs -- Spec path: {spec_path} -- Issue: #{issue_number} (if applicable) - -## Constraints -- Read the skill instructions first, then follow them exactly -- Do not add features beyond the spec -- Fail loudly if something is wrong -- Write all outputs to files (spec updates, test files, code) -- Read the Security Considerations section of the spec. Follow `shared/security-lens.md` patterns for any auth/RLS/edge function/input validation work -- Before reporting done, re-read the acceptance criteria from the spec -- For each criterion, assess: ✅ satisfied / ⚠️ partially satisfied or unsure / ❌ not satisfied -- Include a 🔒 Security line in your satisfaction assessment (see `shared/security-lens.md` Review-Time section) -- Be honest — flag anything you couldn't verify or are uncertain about -- When done, report: what you did, what files changed, satisfaction assessment, current artifact state -``` - -### Diagnose Sub-Agent Prompt - -For bug investigation, the manager does triage first (reads issue, asks user questions), then dispatches with pre-filled context. Use this variant instead of the generic template: - -``` -You are investigating a bug. - -## Bug Context (from manager triage) -- **Issue:** #{issue_number} (or "untracked") -- **Actual behavior:** {what_happens} -- **Expected behavior:** {what_should_happen} -- **Reproduction:** {steps} -- **Started:** {when} -- **Environment:** {details} - -## Files to Read -- Skill instructions: ~/.claude/skills/diagnose/SKILL.md -- Spec I/O reference: ~/.claude/skills/shared/spec-io.md -- GitHub ops: ~/.claude/skills/shared/github-ops.md -- Project context: {AGENTS.md path} - -## Constraints -- Do NOT ask the user questions — all context is above -- Investigate the codebase: search for the code path, check git history, find root cause -- Write a bug spec to Documents/specs/ -- Return: root cause summary, files involved, draft spec path, satisfaction assessment -``` - -### Narrating Dispatches - -**Before dispatching**, tell the human what you're doing: - -``` -📤 Dispatching: spec-review - Input: Documents/specs/42-dark-mode-spec.md - Reading: spec-review/SKILL.md, shared/spec-io.md -``` - -**After sub-agent returns**, report the result. For implementation skills, include the satisfaction assessment: - -``` -📥 spec-review complete - Result: 3 gaps found (missing non-goals, vague criterion #4, no error states) - Files changed: none (read-only skill) - Next: [GATE A] Your approval needed -``` - -``` -📥 implement-direct complete - Files changed: QuoteForm.tsx, useQuotePrice.ts - Satisfaction: - ✅ Price updates on service change - ✅ Notary fee displays separately - ⚠️ Hourly rate message — implemented but copy may not match spec - ✅ Total reflects all line items - 🔒 Security: RLS policies added for new table, input validated - Next: [GATE B] Your review — 1 item flagged -``` - -### After Sub-Agent Returns - -1. Read the sub-agent's summary -2. Check the satisfaction assessment (for implementation skills): - - All ✅ → proceed to next step normally - - Any ⚠️ → include flags in Gate B presentation so human knows what to check - - Any ❌ → ask sub-agent to fix before presenting Gate B -3. Verify the artifact was updated (check spec status, test plan status, etc.) -4. Report using the narration format above -5. **Handle GitHub updates** (the manager owns all GitHub writes): - - After implementation: ask user, then post implementation notes + set status to "In Review" - - After diagnose: ask user, then post diagnosis comment - - See `shared/github-ops.md` for posting patterns -6. If the next step is a **human gate**, present the gate clearly and wait -7. If the next step is another skill with no gate, propose it: "Proceeding to {skill}. OK?" - -### Human Gates — How to Present - -**Gate A (after spec-review):** -``` -Spec review complete. Here's the assessment: -{summary from spec-review sub-agent} - -Your decision: -1. Approve — and choose: TDD or Direct implementation? -2. Revise — I'll update the spec based on your feedback -``` - -**Gate B (after implementation):** -``` -Implementation complete. {summary} -{satisfaction assessment with any ⚠️ flags} - -Your decision: -1. Looks good — I'll update GitHub issue #{number} and proceed to QA handoff -2. Changes needed — describe what to fix -``` - -**Gate C (after security critique):** -``` -Security backlog ranked. {summary of top items} - -Your decision: -1. Proceed — start fixing from the top -2. Reprioritize — tell me what to change -``` - ---- - -## Quick Start: "I don't know where I am" - -Check these in order. First match tells you where you are and what to do. - -| # | Check | If true | Do this | -|---|-------|---------|---------| -| 1 | `SECURITY_PLAN.md` exists with Pending or Ranked items? | Yes | You're in the **security path**. See [Security Decision Tree](#security-path) below. | -| 2 | User mentions a bug, error, or issue to investigate? No bug spec exists yet? | Yes | Enter **Bug Path**. Start triage, then dispatch `diagnose` sub-agent. | -| 3 | No spec file in `Documents/specs/`? | Yes | Nothing started. Run `/interview` directly (with issue number if you have one). | -| 4 | Spec exists, status is `Draft`? | Yes | Spec needs review. Dispatch `spec-review` sub-agent. | -| 5 | Spec status is `Approved`, no `## Test Plan` section? | Yes | **[Human Gate A passed.]** Ask: TDD or Direct? Then dispatch accordingly. | -| 6 | `Test Plan` section exists, status is `Planned`? | Yes | Dispatch `write-failing-test` sub-agent. | -| 7 | `Test Plan.status` is `Tests Written`? | Yes | Dispatch `implement-to-pass` sub-agent. | -| 8 | Spec status is `Implemented`? | Yes | **[Human Gate B]** Ask human to review PR. | -| 9 | `Test Plan.status` is `Passing`? | Yes | **[Human Gate B]** Ask human to review PR. | -| 10 | Bug spec exists in `Documents/specs/` with `Approved` status? | Yes | Ask: TDD or Direct? Then dispatch accordingly. | -| 11 | None of the above match | — | Check `git log` and the GitHub issue for context. Or start fresh with `/interview`. | - ---- - -## State Model - -State is derived from observable artifacts — no separate state file. Skills declare which artifact they use via `state_source` in their contract. - -### Artifact 1: Spec File - -**Location:** `Documents/specs/{issue}-{slug}-spec.md` -**Used by:** All feature-path and bug-path skills. -**How to read:** See `shared/spec-io.md`. - -| Field | Where in file | Values | Who sets it | -|-------|---------------|--------|-------------| -| `status` | Header `**Status:**` line | `Draft`, `Approved`, `Implemented` | `interview` creates as Draft. Human sets Approved after spec-review. `implement-direct` sets Implemented. | -| `Test Plan.status` | `## Test Plan` section `**Status:**` line | `Planned`, `Tests Written`, `Passing` | `plan-tests` → `write-failing-test` → `implement-to-pass` | -| `issue_number` | Header `**Issue:**` line | integer | `interview` | - -### Artifact 2: SECURITY_PLAN.md - -**Location:** Project root -**Used by:** Security-path skills (phases 1–4). - -| Field | Meaning | Values | Who sets it | -|-------|---------|--------|-------------| -| `findings` | Initial scan results | `Pending` | `1-security-audit` | -| `backlog` | Prioritized list | `Ranked` | `2-security-critique` | -| `current_item.test` | Test for top item | `Written` | `3-security-spec` | -| `current_item.status` | Fix status for top item | `DONE` | `4-security-fix` | - -### Artifact 3: GitHub Issue (external) - -Managed via `gh` CLI. See `shared/github-ops.md` for all operations. Also the state source for the bug path — `diagnose` reads and writes state here when no spec exists. - -| Status | Meaning | Set by | -|--------|---------|--------| -| `Backlog` | Created, not scheduled | `interview` (asks user) | -| `Ready` | Spec approved, waiting | User or `diagnose` | -| `In Progress` | Being implemented | User | -| `In Review` | PR open | `implement-to-pass` or `implement-direct` | -| `QA` | Needs manual testing | `qa-handoff` | -| `Done` | Merged | User | - ---- - -## Skill Index - -All skills. Scannable by tag. The `Next` column is what's valid after a skill completes. - -| Skill | Tags | State Source | Human Gate After? | Next | -|-------|------|--------------|-------------------|------| -| `interview` | intake, requirements, spec-creation, github | spec | No | spec-review | -| `spec-review` | intake, review, quality-gate | spec | **YES (Gate A)** | plan-tests, implement-direct | -| `plan-tests` | tdd, test-planning | spec | No | write-failing-test | -| `write-failing-test` | tdd, testing, red-phase | spec | No | implement-to-pass | -| `implement-to-pass` | tdd, implementation, green-phase | spec | **YES (Gate B)** | qa-handoff | -| `implement-direct` | implementation, direct | spec | **YES (Gate B)** | qa-handoff | -| `diagnose` | bug, diagnosis, investigation, spec-creation | github_issue | No | plan-tests, implement-direct | -| `qa-handoff` | closure, qa, github | spec | No | *(terminal)* | -| `1-security-audit` | security, audit, security-phase-1 | security_plan | No | 2-security-critique | -| `2-security-critique` | security, audit, security-phase-2 | security_plan | **YES (Gate C)** | 3-security-spec | -| `3-security-spec` | security, audit, security-phase-3, tdd | security_plan | No | 4-security-fix | -| `4-security-fix` | security, audit, security-phase-4, implementation | security_plan | No | 3-security-spec *(loop)* | -| `full-security-audit` | security, orchestrator | security_plan | No | 1-security-audit | -| `supabase-security` | security, reference | — | No | *(reference only)* | - -### Tag Lookup - -Find skills by capability, not name. - -| Tag | Skills | -|-----|--------| -| `intake` | interview, spec-review | -| `requirements` | interview | -| `review` | spec-review | -| `quality-gate` | spec-review | -| `tdd` | plan-tests, write-failing-test, implement-to-pass, 3-security-spec | -| `testing` | write-failing-test | -| `red-phase` | write-failing-test | -| `green-phase` | implement-to-pass | -| `test-planning` | plan-tests | -| `implementation` | implement-to-pass, implement-direct, 4-security-fix | -| `direct` | implement-direct | -| `bug` | diagnose | -| `diagnosis` | diagnose | -| `closure` | qa-handoff | -| `qa` | qa-handoff | -| `github` | interview, qa-handoff | -| `security` | 1-security-audit, 2-security-critique, 3-security-spec, 4-security-fix, full-security-audit, supabase-security | -| `spec-creation` | interview, diagnose | -| `investigation` | diagnose | -| `audit` | 1-security-audit, 2-security-critique, 3-security-spec, 4-security-fix | - ---- - -## Decision Trees - -Mechanical step-by-step. Follow top-to-bottom. Conditions check state model fields above. Each step says what to invoke and with what arguments. - -### Feature Path: TDD - -``` -STEP 1: Spec exists? - NO → invoke /interview directly → STEP 2 - YES → STEP 2 - -STEP 2: Spec status? - Draft → dispatch spec-review sub-agent → STEP 3 - Approved → STEP 4 - -STEP 3: [HUMAN GATE A] Spec review complete. - STOP. Present findings to human. - "Approved, TDD" → set spec status to Approved → STEP 4 - "Approved, Direct" → set spec status to Approved → Direct Path STEP 4 - "Revise" → back to STEP 1 - -STEP 4: Test Plan section exists? - NO → dispatch plan-tests sub-agent → STEP 5 - YES → read Test Plan.status → STEP 5 - -STEP 5: Test Plan.status? - Planned → dispatch write-failing-test sub-agent → STEP 6 - Tests Written → STEP 6 - Passing → STEP 7 - -STEP 6: dispatch implement-to-pass sub-agent → STEP 7 - -STEP 7: [HUMAN GATE B] Implementation complete. - STOP. Human reviews PR. - "Approved" → STEP 8 - "Changes" → human edits → STEP 6 - -STEP 8: dispatch qa-handoff sub-agent - DONE. -``` - -### Feature Path: Direct - -``` -STEP 1–3: Same as TDD path. - -STEP 4: dispatch implement-direct sub-agent - -STEP 5: [HUMAN GATE B] Verify manually. - STOP. Human tests the feature. - "Looks good" → STEP 6 - "Broken" → back to STEP 4 - -STEP 6: dispatch qa-handoff sub-agent - DONE. -``` - -### Bug Path - -``` -STEP 1: Bug triage (manager does this in-conversation) - a. If issue number provided, read it: `gh issue view #N` - b. Ask the human (skip any already answered by the issue): - - What's actually happening? - - What should happen? - - How to reproduce? - - When did it start? - - Environment? - c. Dispatch diagnose sub-agent with triage context → STEP 2 - -STEP 2: Diagnose sub-agent returns - Review findings and draft bug spec. - Present to human: "Here's what the investigation found: {summary}" - Confirm spec is accurate. - If tracked in GitHub → post diagnosis comment (with user confirmation). - NOTE: diagnose generates a bug spec (status: Approved). - Bug specs skip the interview/review cycle. - -STEP 3: [Human chooses path] - TDD → dispatch plan-tests sub-agent → continue with TDD Feature Path STEP 5+ - Direct → dispatch implement-direct sub-agent → continue with Direct Feature Path STEP 5+ - -STEP 4: Bug tracked in GitHub? - YES → dispatch qa-handoff sub-agent - NO → DONE. -``` - -### Security Path - -``` -STEP 1: dispatch 1-security-audit sub-agent - Creates SECURITY_PLAN.md with findings as Pending. - -STEP 2: dispatch 2-security-critique sub-agent - Removes false positives, ranks items. - -STEP 3: [HUMAN GATE C] Backlog ranked. Human reviews priorities. - STOP. Present ranked backlog to human. - "Looks right" → STEP 4 - "Reprioritize" → human edits → STEP 2 - -STEP 4: [LOOP CHECK] Pending items in ranked backlog? - NO → DONE. All items fixed or acknowledged. - YES → STEP 5 - -STEP 5: dispatch 3-security-spec sub-agent - Picks top Pending item. Writes failing test. - -STEP 6: dispatch 4-security-fix sub-agent - Implements fix. Marks item DONE. - → back to STEP 4 -``` - ---- - -## Human Gates - -Three mandatory approval points across all paths. The manager must STOP at these. Do not auto-proceed. - -| Gate | After skill | Before skill | Human decides | -|------|-------------|--------------|---------------| -| **Gate A** | spec-review | plan-tests / implement-direct | "Approve spec and choose TDD or Direct" or "Revise" | -| **Gate B** | implement-to-pass / implement-direct | qa-handoff | "PR looks good, proceed" or "Changes needed" | -| **Gate C** | 2-security-critique | 3-security-spec | "Ranked backlog looks right, proceed" or "Reprioritize" | - ---- - -## Constraints & Invariants - -Rules the manager enforces. A skill violating these should not be invoked. - -1. **No implementation before approval.** `plan-tests`, `write-failing-test`, `implement-to-pass`, `implement-direct` all require `status: Approved`. Never invoke them on a Draft spec. -2. **TDD is sequential.** `write-failing-test` requires `Test Plan.status: Planned`. `implement-to-pass` requires `Tests Written`. Cannot skip or reorder. -3. **Security path is isolated.** Security skills use `state_source: security_plan`. They don't read or write spec files. They don't participate in feature or bug paths. -4. **`qa-handoff` is terminal.** Nothing follows it. Workflow is complete after qa-handoff runs. -5. **Bug path uses a bug spec.** `diagnose` generates a lightweight bug spec with status `Approved`. Bug specs skip interview/review and flow directly into TDD or direct implementation. -6. **Human gates are mandatory.** The manager stops at Gate A, Gate B, and Gate C. Never auto-proceeds past them. -7. **Manager stays clean.** Never load skill implementation details into your own context. Dispatch to sub-agents. Your job is routing, not executing. - ---- - -## Shared Primitives - -Referenced by multiple skills. Not skills themselves — reference docs. - -| File | Used by | What it covers | -|------|---------|----------------| -| `shared/github-ops.md` | interview, diagnose, implement-direct, implement-to-pass, qa-handoff | All `gh` CLI patterns: comments, status, project board, PR linking | -| `shared/spec-io.md` | interview, plan-tests, write-failing-test, implement-direct, qa-handoff, spec-review | Spec file structure, sections, status fields, how to read/write | -| `shared/security-lens.md` | interview, implement-direct, implement-to-pass, spec-review | Design-time security questions, implementation patterns, review checklist | +You are the orchestrator. Your job is to stay oriented, determine the right skill to run, and guide the human through the workflow. + +## 🎯 Visible Handshake +At the start of every session, you MUST announce: +> 🎯 **Workflow Manager active. Checking project state...** + +## 1. Orientation Todo List +On invocation, perform these steps: + +- [ ] Check `active-context.md` for current work +- [ ] Check git branch and status +- [ ] Check `Documents/specs/` for active spec files +- [ ] Propose next phase (Understand / Test / Build / Deliver) + +## 2. Decision Matrix + +| # | Check | Current Phase | Next Action | +|---|-------|---------------|-------------| +| 1 | Active todo list exists? | Mid-task | Resume current todos | +| 2 | SECURITY_PLAN.md with pending items? | Security Path | Continue security pipeline | +| 3 | User mentions bug/error? | Bug Path | Run /diagnose | +| 4 | No spec in `Documents/specs/`? | Fresh Start | Run /understand | +| 5 | Spec status: `Draft`? | Understanding | Continue /understand | +| 6 | Spec status: `Approved`, no tests? | Ready to Build | Ask: **TDD** or **Direct**? | +| 7 | Spec status: `Approved`, tests exist? | Ready to Build | Run /build mode:tdd | +| 8 | Spec status: `Implemented`? | Gate B | Present for Review | +| 9 | PR approved? | Ready to Deliver | Run /deliver | + +## 3. Human Gates +- **Gate A**: After `understand` → Approve spec & choose mode. +- **Gate B**: After `build` → Review implementation. +- **Gate C**: After security critique → Approve priorities. + +## 4. Execution Rules +- **Claude Code**: Dispatch `/test` as a sub-agent. Run others in main context. +- **Cursor**: Run everything in main context. Use `.cursor/rules/` for guidance. +- **Todos**: Every skill MUST generate a task-specific todo list on invocation.