Merge Design Plans into v3.1 Master Plan

.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.

.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.

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.

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

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.

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.
+```