omniconductor 0.3.0

package/core/universal-rules/spec-as-you-go.md

@@ -0,0 +1,123 @@
+---
+rule_id: spec-as-you-go
+rule_name: "Same-turn spec update + real-time docs sync"
+severity: ABSOLUTE
+applies_to: ["all-tools"]
+violation_count: 5+
+enforcement:
+  - hook: stop-session-log-check
+  - llm-self-discipline
+linked_rules:
+  - workflow
+  - quality-gates
+---
+
+# Spec-as-you-go — Same-Turn Documentation Sync
+
+> Bundles W3 (spec update in same turn as code edit) and O1 (real-time docs sync). Documentation drift is the most common rule violation in production; the rule treats it as a code-level concern, not a "will do later" concern.
+
+## 1. The Same-Turn Update Rule (W3)
+
+Code change without same-turn doc update is a rule violation, period.
+
+### 1.1 What "same turn" means
+
+If the orchestrator (or a delegated role) edits a source file in turn N, the corresponding spec / architecture / decision doc MUST be updated **in the same turn N**, not in a follow-up turn, not in an end-of-session batch, not in tomorrow's commit.
+
+### 1.2 What needs same-turn update — by change type
+
+| Code change | Doc to update (same turn) |
+|---|---|
+| New API route / endpoint | spec for that area + frontmatter `api_routes:` list |
+| New page / route | spec for that area + frontmatter `pages:` list |
+| New component (reusable) | spec for that area + frontmatter `components:` list |
+| New service / hook | spec for that area + frontmatter `services:` / `hooks:` list |
+| Behavior change (existing flow) | "Flow" or "Known constraints" section of relevant spec |
+| New DB table / column | DB schema spec section (or dedicated `DATABASE.md`) |
+| New environment variable | env-vars section of relevant spec + onboarding doc |
+| New external service integration | architecture doc + services index |
+
+### 1.3 Why same-turn (not end-of-session)
+
+End-of-session batching always loses fidelity. By turn N+5, the orchestrator no longer remembers that turn N also touched a database column. Stop-hook reminders catch some of this post-hoc, but the rule is designed to make Stop-hook unnecessary in the first place.
+
+Documented production failure: a multi-file refactor changed 4 service signatures. The session ended without spec update. Days later a different agent edited one of those services, read the stale spec, and reverted to the old signature. The fix took longer than the original refactor.
+
+### 1.4 Where to put a new spec
+
+If the area you're touching does not yet have a `docs/specs/<area>.md`, CREATE IT in the same turn. Use `core/docs-templates/specs/_example.md` (shipped by every CONDUCTOR adapter) as the starting point.
+
+---
+
+## 2. Real-Time Docs Sync (O1)
+
+When work is committed and pushed, the orchestrator MUST update the following docs in the same turn:
+
+- `docs/CURRENT_WORK.md` — session state, what was done, what's next.
+- `docs/REMAINING_TASKS.md` (if it exists) — mark completed tasks, surface new ones.
+- `docs/TASKS.md` (if it exists) — phase-level checklist.
+- The relevant spec(s) per the table in section 1.2.
+- `docs/INDEX.md` (if a new doc was created in this turn).
+
+### 2.1 The "completed task delete" sub-rule
+
+When a task in CURRENT_WORK.md or TASKS.md is moved to status `completed`, it should be DELETED in the next session boundary, not left as historical clutter. The session log itself is the historical record. CURRENT_WORK.md is for what is current, not what was done last week. (Full rule: `operations.md` section 2.)
+
+### 2.2 What the orchestrator does NOT update
+
+- Session transcripts / chat exports — those are tool-specific and out of scope.
+- External tracker tickets (Jira / Linear / GitHub Issues) — those are explicit user actions, not auto-sync.
+- Generated files (lockfiles, type-gen output) — those self-update via tooling.
+
+---
+
+## 3. Frontmatter convention (CONDUCTOR schema)
+
+Spec files use YAML frontmatter so adapter `transform.sh` can route them. The CONDUCTOR-native fields:
+
+```yaml
+---
+spec_id: <kebab-case-area-name>
+api_routes:
+  - "/api/foo"
+  - "/api/bar"
+pages:
+  - "/foo"
+components:
+  - FooCard
+services:
+  - getFooById
+hooks:
+  - useFooState
+---
+```
+
+Per-tool transformations:
+
+- **Claude Code**: keep as-is in `docs/specs/<area>.md`. Stop-hook checks for stale frontmatter when source files in that area are touched.
+- **Cursor / Copilot / Windsurf**: same file path, frontmatter preserved. Tool-specific scoping (`globs:` / `applyTo:`) added by the relevant adapter when the file lives under `.cursor/rules/` or `.github/instructions/`.
+- **Gemini / Codex**: file is referenced by path inside the single GEMINI.md / codex.md.
+
+---
+
+## 4. Enforcement mechanism matrix
+
+| Mechanism | Trigger | Action |
+|---|---|---|
+| `stop-session-log-check` (Claude hook) | Recent commit + stale CURRENT_WORK.md | Block stop, inject reminder |
+| `stop-session-log-check` (Claude hook) | Source files changed > 3 + zero spec files touched | Block stop, inject "spec-as-you-go" reminder |
+| Rule text (other tools) | Same as above | Manual reminder; user catches |
+
+For tools without hook support, the orchestrator MUST self-check before declaring a turn complete:
+
+1. Did this turn write to source files? → spec update done?
+2. Did this turn produce a commit? → CURRENT_WORK.md updated?
+3. Did this turn complete a task? → status moved to `completed`, scheduled for delete?
+
+If any answer is "no", the turn is not complete.
+
+---
+
+## 5. Test coverage sync (cross-link)
+
+Test coverage sync (every new feature / changed behavior MUST have a corresponding e2e test added or updated in the same PR) is documented in `quality-gates.md` section 3. This rule and that rule are siblings: spec-as-you-go covers documentation; test coverage sync covers verifiability. Both are ABSOLUTE.

package/core/universal-rules/workflow.md

@@ -0,0 +1,153 @@
+---
+rule_id: workflow
+rule_name: "Plan-first, docs-first, process-first"
+severity: ABSOLUTE
+applies_to: ["all-tools"]
+violation_count: 6+
+enforcement:
+  - hook: stop-session-log-check
+  - llm-self-discipline
+linked_rules:
+  - spec-as-you-go
+  - meta-discipline
+---
+
+# Workflow — Plan-First Order
+
+> CONDUCTOR universal rule. Bundles W1, W2, W4, W5, W6 into a single source-of-truth that every supported tool inherits via its adapter.
+
+## 1. Plan-First Order (W1)
+
+Before writing any non-trivial code or modifying configuration, the orchestrator MUST follow this sequence:
+
+```
+Plan → Architecture → Tasks → Implementation
+```
+
+**Plan** = What the user actually asked for, restated in 1-3 sentences. List of touched files. Open questions surfaced.
+
+**Architecture** = How it fits the existing system (data flow, dependency direction, no new layers without justification).
+
+**Tasks** = Ordered list with stop conditions. Each task is independently committable.
+
+**Implementation** = Code edits + tests + docs sync, in the same turn.
+
+### 1.1 When to write a `.plan.md`
+
+| Scope | `.plan.md` required? |
+|---|---|
+| Trivial (rename, copy edit) | No |
+| Simple (1-2 files, established pattern) | No |
+| Medium (3+ files, new behavior) | Yes |
+| Large (cross-cutting, new system) | Yes — and reviewer agent validates before implementation |
+
+### 1.2 Why this rule exists (origin)
+
+The originating project counted **6+ violations** of this order during early production work. Each violation produced rework (wrong file touched, missed test, broken dependency). The rule was promoted to ABSOLUTE after the 6th catch.
+
+### 1.3 Pre-implementation checklist (orchestrator self-check)
+
+Before any tool call that writes code:
+
+- [ ] Plan stated to user (1-3 sentences) or `.plan.md` exists.
+- [ ] Architecture verified against existing patterns (no new layers added unintentionally).
+- [ ] Task list visible (TodoWrite or inline numbered list).
+- [ ] Stop condition for current task is explicit.
+
+If any box is unchecked → STOP, complete the missing step, then proceed.
+
+---
+
+## 2. Docs-First for Ad-Hoc Work (W2)
+
+Work that arrives outside the active plan (user requests, bug reports, suggestions) MUST be logged in `docs/CURRENT_WORK.md` BEFORE implementation begins, not after.
+
+### 2.1 Decision tree
+
+```
+Is the request part of the active plan?
+├─ Yes → implement → push → docs sync (in-turn)
+└─ No  → docs/CURRENT_WORK.md update FIRST (one-line entry)
+         → implement
+         → push
+         → docs sync (specs + CURRENT_WORK status)
+```
+
+### 2.2 What goes in CURRENT_WORK.md
+
+- One-line description of the new ad-hoc task.
+- Source (user message, error report, observation).
+- Status: `In Progress` / `Blocked` / `Done`.
+- Owner: `orchestrator` / `<role>` / `user`.
+
+The point: an outside observer (or the orchestrator at session resume) can see what surfaced today and where it stands without reading the chat history.
+
+---
+
+## 3. The 7-Step Workflow (W4)
+
+For any feature / bug / chore that produces a commit, all 7 steps MUST occur in order:
+
+1. **Plan** — restate request, list files.
+2. **Architecture** — verify fit with existing system.
+3. **Tasks** — ordered list with stop conditions.
+4. **Execute** — code edits with same-turn spec updates.
+5. **Test** — run quality gates (`quality-gates.md`).
+6. **Push** — commit + push (or PR per branch strategy).
+7. **Docs** — sync CURRENT_WORK + relevant specs + plans.
+
+If a step fails, the workflow does NOT skip to the next step. The orchestrator stops, fixes, then continues. Even if step 6 fails (e.g., CI red), step 7 still updates docs to record the failure.
+
+---
+
+## 4. Process Over Speed (W5)
+
+User shortcut phrases ("just do it", "go ahead", "fast", "skip", "quickly") DO NOT grant permission to skip workflow steps. They grant permission to PROCEED at the next decision point — they do not retroactively waive Plan-First or Docs-First.
+
+If the user request is ambiguous about scope or destination, the orchestrator MUST consult the ambiguity policy in `meta-discipline.md` (AMB triggers) and ASK rather than guess.
+
+### 4.1 The "discipline over willpower" principle
+
+The 6+ violations of W1 happened because the orchestrator interpreted "let's go" as a license to skip the plan. The corrective rule:
+
+> **Discipline is a system, not willpower.** When ambiguous, ASK. The system must produce the right behavior even when the operator is tired or rushed.
+
+This is not a soft suggestion. The orchestrator that catches itself about to skip a step is REQUIRED to fix course (see W6).
+
+---
+
+## 5. ABSOLUTE Rules Never Skip (W6)
+
+No user instruction grants exemption from rules marked `severity: ABSOLUTE` in any universal-rule frontmatter. This includes:
+
+- Pre-commit / pre-merge code review (`quality-gates.md`).
+- Spec-as-you-go updates (`spec-as-you-go.md`).
+- Test coverage sync (`quality-gates.md`).
+- Framework originality (`meta-discipline.md`).
+- Plan-first / docs-first / process-over-speed (this file).
+
+If the orchestrator realizes mid-turn that an ABSOLUTE rule was skipped, the orchestrator MUST:
+
+1. Stop the current action.
+2. Surface the violation in the next user-facing message ("I broke W3 — I committed without updating the spec. Fixing now.").
+3. Repair the gap.
+4. Continue.
+
+Silent recovery (fixing without acknowledging) is WORSE than explicit acknowledgment. The user needs visibility into rule failures so they can intervene if the recovery itself is wrong.
+
+### 5.1 Origin
+
+Production case: a PR was merged with the pre-merge code review skipped. The orchestrator told the user it was done, did not mention the skip, and the user caught it manually two days later. The corrective rule made silent skip equally serious as the original violation.
+
+---
+
+## Cross-tool enforcement
+
+| Mechanism | Tools that support it natively |
+|---|---|
+| Stop hook (auto-injects reminder when CURRENT_WORK is stale) | Claude Code |
+| PreToolUse hook (blocks invalid sub-agent dispatch) | Claude Code |
+| File-glob rule scoping (`paths:` / `globs:` / `applyTo:`) | Claude Code, Cursor, Copilot, Windsurf (dir-based) |
+| Rule text + LLM self-discipline | All tools |
+
+On tools without hook support, this file's text IS the enforcement. The `linked_rules` frontmatter and the cross-references (W6 → meta-discipline.md AMB triggers) keep the chain navigable manually.

package/core/workflow/PHASES.md

@@ -0,0 +1,134 @@
+# PHASES — detailed entry/exit criteria per workflow phase
+
+> **Status (P0 foundation): PLACEHOLDER.** This file describes intent and structure. P1 fills each phase section with concrete content sanitized from the reference adopter.
+
+## How to read this file
+
+For each of the 6 phases (Plan / Architecture / Tasks / Implementation / Review / Spec), the same template:
+
+```
+### [Phase name]
+
+**Trigger**: what user request or upstream phase entry produces this phase.
+**Owner**: who carries the work (orchestrator / specialized agent persona / human).
+**Inputs**: artifacts that MUST exist before entering.
+**Outputs**: artifacts produced before exit.
+**Entry criteria**: bullet list — all must be true to enter.
+**Exit criteria**: bullet list — all must be true to advance.
+**Anti-patterns**: things people do wrong; how to recognize and recover.
+**Tool-specific notes**: callouts for Claude / Cursor / others where mechanism differs.
+```
+
+---
+
+## 1. PLAN
+
+**Trigger**: medium+ scope request.
+
+**Owner**: orchestrator (Claude main session) or human (other tools).
+
+**Inputs**: user request, prior context (`docs/CURRENT_WORK.md`).
+
+**Outputs**: `.plan.md` describing approach, files affected, risks, stop condition.
+
+**Entry criteria** (P1 fill):
+- Request scope assessed (Trivial / Simple / Medium / Large).
+- If Trivial / Simple → SKIP this phase, go to Tasks.
+
+**Exit criteria** (P1 fill):
+- `.plan.md` exists with ≥ N sections.
+- Reviewer-eligible (medium → human ack; large → reviewer agent ack).
+
+**Anti-patterns** (P1 fill).
+
+---
+
+## 2. ARCHITECTURE
+
+**Trigger**: large scope work that affects system-level shape (auth flow, data model, billing).
+
+**Owner**: strategist agent (Claude) or human (other tools).
+
+**Inputs**: `.plan.md`.
+
+**Outputs**: ADR(s) under `docs/architecture/`; updated system diagram.
+
+**Entry / exit / anti-patterns**: P1 fill.
+
+---
+
+## 3. TASKS
+
+**Trigger**: plan approved (medium+) OR direct request (simple).
+
+**Owner**: orchestrator (Claude) or human.
+
+**Inputs**: `.plan.md` (medium+) or request alone (simple).
+
+**Outputs**: enumerated task list with: objective, file paths, constraints (`must_do`, `must_not_do`), output paths, stop condition.
+
+**Entry / exit / anti-patterns**: P1 fill.
+
+---
+
+## 4. IMPLEMENTATION
+
+**Trigger**: tasks ready.
+
+**Owner**: builder / helper / designer / mailer / translator / scribe agent (Claude) or human.
+
+**Inputs**: task list.
+
+**Outputs**: code + e2e test updates per task.
+
+**Entry / exit / anti-patterns**: P1 fill (will include "one task per agent", "no general-purpose agent", "model override per R2").
+
+---
+
+## 5. REVIEW
+
+**Trigger**: implementation task complete.
+
+**Owner**:
+- Stage A: code-reviewer agent (Claude) or human (other tools).
+- Stage B: `/code-review` slash command (Claude + Cursor partial) or human (other tools).
+
+**Inputs**: git diff (Stage A) or open PR (Stage B).
+
+**Outputs**: reviewer report; either pass-through or block-on-issues.
+
+**Entry / exit / anti-patterns**: P1 fill (will include "block on HIGH-confidence ≥75 issues", "specialized reviewer agents per change kind").
+
+---
+
+## 6. SPEC
+
+**Trigger**: implementation merged.
+
+**Owner**: scribe agent (Claude) or human.
+
+**Inputs**: shipped code; existing `docs/specs/<area>.md`.
+
+**Outputs**: updated spec reflecting actual shipped behavior.
+
+**Entry / exit / anti-patterns**: P1 fill (will include "spec-as-you-go ABSOLUTE", "Stop hook enforcement on Claude", "rule reminder on others").
+
+---
+
+## Phase scaling reminder
+
+| Scope | Phases entered | Notes |
+|---|---|---|
+| Trivial | 4, 5, 6 | Skip Plan + Architecture + Tasks. |
+| Simple | 3, 4, 5, 6 | Skip Plan + Architecture. |
+| Medium | 1, 3, 4, 5, 6 | Skip Architecture. |
+| Large | 1, 2, 3, 4, 5, 6 | Full ceremony. |
+
+## Tool-agnostic enforcement reminder
+
+Workflow definition is universal. Enforcement degrades:
+
+- **Claude Code**: Stop hooks can block phase-skipping at commit time (e.g., no `.plan.md` for medium+ → blocked).
+- **Cursor / Copilot / Gemini / Codex / Windsurf**: rule text reminds. Self-policed.
+
+See `docs/COMPATIBILITY-MATRIX.md` for the per-tool enforcement column.

package/core/workflow/README.md

@@ -0,0 +1,56 @@
+# `core/workflow/` — Universal workflow definition
+
+The Plan → Architecture → Tasks → Implementation → Review → Spec workflow that every CONDUCTOR project follows, regardless of which AI coding tool drives it.
+
+## The 6 phases
+
+```
+Request
+   ↓
+1. PLAN              — clarify intent + write .plan.md (medium+ scope only)
+   ↓
+2. ARCHITECTURE      — system-level shape, ADRs, contracts (large scope only)
+   ↓
+3. TASKS             — break plan into discrete tasks with file paths + stop conditions
+   ↓
+4. IMPLEMENTATION    — execute one task at a time, delegated when possible
+   ↓
+5. REVIEW            — Stage A pre-commit + Stage B pre-merge PR
+   ↓
+6. SPEC              — update docs/specs/* to reflect what shipped
+```
+
+## Phase scaling by scope
+
+Not every change goes through all 6 phases. Scale the workflow to scope:
+
+| Scope | Files | Phases entered | Review checkpoint |
+|---|---|---|---|
+| Trivial | 1 | 4, 5, 6 | None |
+| Simple | 1-2 | 3, 4, 5, 6 | None |
+| Medium | 3-10 | 1, 3, 4, 5, 6 | Plan → Implement → Review |
+| Large | 10+ | 1, 2, 3, 4, 5, 6 | Architecture → Plan → Implement → Review |
+
+## What lives here
+
+- `PHASES.md` — detailed entry/exit criteria per phase. (P1: filled with full content derived from the reference adopter's workflow.)
+- (future) `templates/` — phase output templates (`.plan.md` skeleton, ADR skeleton).
+
+## Tool-agnostic enforcement
+
+The workflow itself is tool-agnostic. Enforcement varies:
+
+- **Claude Code**: Stop hook can verify a `.plan.md` exists for medium+ scope tasks before allowing commits.
+- **Cursor / Copilot / Gemini / Codex / Windsurf**: rule text reminds the user; enforcement is self-policed.
+
+Adapter outputs all reference these phase definitions but the *mechanism* of enforcement is per-tool (see `docs/COMPATIBILITY-MATRIX.md`).
+
+## Why 6 phases (not fewer / more)
+
+- Fewer than 6 (collapse Tasks into Implementation) loses the explicit "what files, in what order" artifact that prevents scope creep mid-implementation.
+- More than 6 (separate Verification phase, etc.) adds ceremony users will skip.
+- The 6 phases match the natural rhythm of a feature, refactor, or bug fix at solo / small-team scale.
+
+## Status (P0 foundation)
+
+`PHASES.md` is a placeholder. P1 fills it with detailed entry/exit criteria, examples, and anti-patterns to avoid per phase.