cognitx-leyton · egouilliard-leyton · Apr 17, 2026 · Apr 17, 2026 · Apr 17, 2026 · Apr 17, 2026
@@ -0,0 +1,141 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Dev Pipeline Workflow</title>
+<style>
+  body { background: #0d1117; color: #c9d1d9; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; padding: 20px; }
+  h1 { color: #58a6ff; border-bottom: 1px solid #30363d; padding-bottom: 10px; }
+  h2 { color: #8b949e; margin-top: 30px; }
+  .mermaid { background: #161b22; border-radius: 8px; padding: 20px; margin: 20px 0; }
+  table { border-collapse: collapse; width: 100%; margin: 20px 0; }
+  th, td { border: 1px solid #30363d; padding: 8px 12px; text-align: left; }
+  th { background: #161b22; color: #58a6ff; }
+  tr:nth-child(even) { background: #161b2211; }
+  code { background: #161b22; padding: 2px 6px; border-radius: 4px; color: #79c0ff; }
+</style>
+</head>
+<body>
+
+<h1>Dev Pipeline Workflow</h1>
+<p>Run with: <code>archon workflow run dev-pipeline "implement issue #N"</code></p>
+
+<div class="mermaid">
+flowchart TD
+    START(["archon workflow run dev-pipeline"]) --> PF
+
+    PF["0. PREFLIGHT<br/>Neo4j + venv + tests + git"]
+    PF -->|"exit 0"| R
+    PF -->|"exit 1"| STOP(["WORKFLOW STOPS"])
+
+    R["1-2. RESEARCH<br/>gh issue view<br/>codegraph queries<br/>nlm CLI / context7"]
+    R --> P
+
+    P["3. PLAN<br/>Read plan_local template<br/>Write plan file"]
+    P --> DC
+
+    subgraph LOOP1 ["dev-cycle — loop node (max 10 iters, 10min idle timeout)"]
+        direction TB
+        I["4. IMPLEMENT<br/>Execute plan tasks<br/>pytest after each change"]
+        I --> RV
+
+        RV["5. REVIEW<br/>feature-dev:code-reviewer<br/>codegraph arch-check"]
+        RV -->|"issues"| FX["FIX issues"]
+        FX --> RV
+        RV -->|"0 issues"| CM
+
+        CM["6. COMMIT<br/>feat/fix/...(scope): why<br/>Co-Authored-By"]
+        CM --> CR
+
+        CR["7. CRITIQUE<br/>Check acceptance criteria<br/>codegraph structural verify"]
+        CR -->|"FAIL"| I
+    end
+
+    DC --> LOOP1
+    LOOP1 -->|"CYCLE_COMPLETE +<br/>until_bash: pytest=0"| RM
+
+    RM["8. ROADMAP<br/>Update ROADMAP.md"]
+    RM --> PK
+
+    PK["9. PACKAGE<br/>Bump 0.1.X+1<br/>python -m build<br/>twine upload"]
+    PK --> TC
+
+    subgraph LOOP2 ["test-cycle — loop node (max 10 iters, 10min idle timeout)"]
+        direction TB
+        T1["Unit tests + compileall"]
+        T1 --> T2["Install test (fresh venv)"]
+        T2 --> T3["Self-index (dogfood)"]
+        T3 --> T4["Leytongo (real-world TS)"]
+        T4 --> T5["Arch check"]
+        T5 -->|"fail"| TF["Fix + re-package"]
+        TF --> T1
+    end
+
+    TC --> LOOP2
+    LOOP2 -->|"TESTS_PASS +<br/>until_bash: pytest=0"| FI
+
+    FI["11. FILE ISSUES<br/>gh issue create<br/>for discoveries"]
+    FI --> PR
+
+    PR["12. CREATE PR<br/>feature to hotfix<br/>+ PyPI version link"]
+    PR --> DONE(["DONE"])
+
+    style PF fill:#1a472a,color:#fff,stroke:#2ea043
+    style STOP fill:#6e1212,color:#fff,stroke:#da3633
+    style DONE fill:#1a472a,color:#fff,stroke:#2ea043
+    style LOOP1 fill:#0d1b2a22,stroke:#1f6feb,stroke-width:2px,color:#c9d1d9
+    style LOOP2 fill:#0d1b2a22,stroke:#1f6feb,stroke-width:2px,color:#c9d1d9
+    style CR fill:#3d2200,color:#fff,stroke:#d29922
+    style T5 fill:#3d2200,color:#fff,stroke:#d29922
+    style I fill:#1a1a3d,color:#fff,stroke:#8957e5
+    style RV fill:#1a1a3d,color:#fff,stroke:#8957e5
+    style CM fill:#1a1a3d,color:#fff,stroke:#8957e5
+</div>
+
+<h2>Safety Mechanisms</h2>
+
+<div class="mermaid">
+flowchart LR
+    subgraph "Each loop exits when ANY of these fire"
+        A["Agent signals<br/>promise COMPLETE"]
+        B["until_bash<br/>pytest exit 0"]
+        C["max_iterations: 10"]
+        D["idle_timeout: 10min"]
+    end
+    A & B --> AND{"BOTH<br/>required"}
+    AND --> EXIT["Loop exits"]
+    C --> EXIT
+    D --> EXIT
+
+    style AND fill:#3d2200,color:#fff,stroke:#d29922
+    style EXIT fill:#1a472a,color:#fff,stroke:#2ea043
+</div>
+
+<h2>Node Details</h2>
+
+<table>
+<tr><th>Step</th><th>Node ID</th><th>Type</th><th>Model</th><th>Key Tools</th></tr>
+<tr><td>0</td><td><code>preflight</code></td><td>bash</td><td>-</td><td>docker, pytest, codegraph</td></tr>
+<tr><td>1-2</td><td><code>research</code></td><td>prompt</td><td>opus</td><td>gh, codegraph CLI, nlm CLI, context7</td></tr>
+<tr><td>3</td><td><code>plan</code></td><td>prompt</td><td>opus</td><td>Read, Write (plan file)</td></tr>
+<tr><td>4-7</td><td><code>dev-cycle</code></td><td>loop</td><td>workflow default</td><td>All tools, code-reviewer agent</td></tr>
+<tr><td>8</td><td><code>roadmap</code></td><td>prompt</td><td>workflow default</td><td>Read, Edit</td></tr>
+<tr><td>9</td><td><code>package</code></td><td>prompt</td><td>workflow default</td><td>build, twine, curl</td></tr>
+<tr><td>10</td><td><code>test-cycle</code></td><td>loop</td><td>workflow default</td><td>pytest, codegraph, pip</td></tr>
+<tr><td>11</td><td><code>file-issues</code></td><td>prompt</td><td>workflow default</td><td>gh issue create</td></tr>
+<tr><td>12</td><td><code>create-pr</code></td><td>prompt</td><td>workflow default</td><td>gh pr create</td></tr>
+</table>
+
+<h2>How to Run</h2>
+<p><code>archon workflow run dev-pipeline "implement issue #12 — expose queries.md as @mcp.prompt() templates"</code></p>
+
+<script type="module">
+import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+mermaid.initialize({
+  startOnLoad: true,
+  theme: 'dark',
+  flowchart: { curve: 'basis', padding: 15 }
+});
+</script>
+</body>
+</html>
@@ -0,0 +1,106 @@
+# Dev Pipeline Workflow
+
+## Overview
+
+```mermaid
+flowchart TD
+    START([Start: archon workflow run dev-pipeline]) --> PF
+
+    PF["/preflight<br/>bash node"]
+    PF -->|PASS| R
+    PF -->|FAIL| STOP([Workflow stops])
+
+    R["/research<br/>codegraph queries + nlm CLI<br/>+ context7 MCP"]
+    R --> P
+
+    P["/plan<br/>Read plan_local template<br/>Write plan file directly"]
+    P --> DC
+
+    subgraph IMPL_LOOP ["Implementation Loop (max 10 iterations)"]
+        direction TB
+        I["Step 4: IMPLEMENT<br/>Execute plan tasks<br/>Validate after each change"]
+        I --> RV
+        RV["Step 5: REVIEW<br/>code-reviewer agent<br/>+ codegraph arch-check<br/>+ dead-code check"]
+        RV -->|issues found| FIX["Fix issues"]
+        FIX --> RV
+        RV -->|clean| C
+        C["Step 6: COMMIT<br/>Conventional commit<br/>+ Co-Authored-By"]
+        C --> CR
+        CR["Step 7: CRITIQUE<br/>Verify acceptance criteria<br/>+ codegraph structural checks"]
+        CR -->|FAIL: gaps found| I
+    end
+
+    DC{dev-cycle<br/>loop node} --> IMPL_LOOP
+    IMPL_LOOP -->|"CYCLE_COMPLETE<br/>+ until_bash passes"| RM
+
+    RM["/roadmap<br/>Update ROADMAP.md"]
+    RM --> PK
+
+    PK["/package<br/>Bump version + build + PyPI"]
+    PK --> TC
+
+    subgraph TEST_LOOP ["Test Loop (max 10 iterations)"]
+        direction TB
+        T1["Stage 1: Unit tests<br/>pytest + compileall"]
+        T1 --> T2
+        T2["Stage 2: Install test<br/>Fresh venv + pip install"]
+        T2 --> T3
+        T3["Stage 3: Self-index<br/>codegraph index on itself"]
+        T3 --> T4
+        T4["Stage 4: Leytongo<br/>Real-world TS project"]
+        T4 --> T5
+        T5["Stage 5: Arch check<br/>codegraph arch-check"]
+        T5 -->|any failure| TFIX["Fix + re-package"]
+        TFIX --> T1
+    end
+
+    TC{test-cycle<br/>loop node} --> TEST_LOOP
+    TEST_LOOP -->|"TESTS_PASS<br/>+ until_bash passes"| FI
+
+    FI["/file-issues<br/>Create GitHub issues for<br/>out-of-scope discoveries"]
+    FI --> PR
+
+    PR["/create-pr<br/>feature → hotfix<br/>with PyPI version link"]
+    PR --> DONE([Done])
+
+    style PF fill:#2d5016,color:#fff
+    style STOP fill:#8b0000,color:#fff
+    style DONE fill:#2d5016,color:#fff
+    style DC fill:#1a3a5c,color:#fff
+    style TC fill:#1a3a5c,color:#fff
+    style CR fill:#5c3a1a,color:#fff
+    style T5 fill:#5c3a1a,color:#fff
+    style IMPL_LOOP fill:#0d1b2a11,stroke:#1a3a5c,stroke-width:2px
+    style TEST_LOOP fill:#0d1b2a11,stroke:#1a3a5c,stroke-width:2px
+```
+
+## Safety Mechanisms
+
+```mermaid
+flowchart LR
+    subgraph "Loop Exit Conditions"
+        A["Agent signals<br/>&lt;promise&gt;COMPLETE&lt;/promise&gt;"]
+        B["until_bash<br/>pytest exit code 0"]
+        C["max_iterations: 10<br/>failsafe"]
+        D["idle_timeout: 10min<br/>hang detection"]
+    end
+
+    A --> EXIT{Exit loop}
+    B --> EXIT
+    C --> EXIT
+    D --> EXIT
+```
+
+## Node Details
+
+| Step | Node ID | Type | Model | Key Tools |
+|------|---------|------|-------|-----------|
+| 0 | `preflight` | bash | - | docker, pytest, codegraph |
+| 1-2 | `research` | prompt | opus | gh, codegraph CLI, nlm CLI, context7 |
+| 3 | `plan` | prompt | opus | Read, Write (plan file) |
+| 4-7 | `dev-cycle` | loop | opus | All tools, code-reviewer agent |
+| 8 | `roadmap` | prompt | sonnet | Read, Edit |
+| 9 | `package` | prompt | sonnet | build, twine, curl |
+| 10 | `test-cycle` | loop | opus | pytest, codegraph, pip |
+| 11 | `file-issues` | prompt | sonnet | gh issue create |
+| 12 | `create-pr` | prompt | sonnet | gh pr create |
@@ -5,6 +5,17 @@ description: |
   Does: preflight -> research -> plan -> implement/review/commit/critique loop -> roadmap -> package -> test -> file-issues -> create-pr
   NOT for: quick one-off fixes, documentation-only changes, manual exploration
 
+  Run with:
+    archon workflow run dev-pipeline --from hotfix --branch feat/issue-<N>-<slug> "implement issue #<N>"
+
+  Examples:
+    archon workflow run dev-pipeline --from hotfix --branch feat/issue-12-mcp-prompts "implement issue #12"
+    archon workflow run dev-pipeline --from hotfix --branch fix/issue-15-unresolved-imports "investigate issue #15"
+    archon workflow run dev-pipeline --from hotfix --branch feat/issue-13-incremental-reindex "implement issue #13"
+
+  Branch naming: feat/ for features, fix/ for bugs, chore/ for maintenance.
+  Always base off hotfix (--from hotfix) to get the latest code.
+
 provider: claude
 model: sonnet
 effort: high
@@ -22,14 +33,17 @@ nodes:
       PASS=true
       echo "=== Pre-flight Checks ==="
 
-      # Git branch
+      # Git branch — should be a feature branch (feat/, fix/, chore/) not main/release/hotfix
       BRANCH=$(git branch --show-current)
-      if [ "$BRANCH" = "dev" ]; then
-        echo "PASS: on dev branch"
-      else
-        echo "FAIL: on $BRANCH, expected dev"
-        PASS=false
-      fi
+      case "$BRANCH" in
+        main|release|hotfix)
+          echo "FAIL: on protected branch $BRANCH — use --branch feat/issue-N-slug"
+          PASS=false
+          ;;
+        *)
+          echo "PASS: on branch $BRANCH"
+          ;;
+      esac
 
       # Working tree
       DIRTY=$(git status --porcelain | grep -v '^\?\?' | head -1)
@@ -69,21 +83,6 @@ nodes:
         PASS=false
       fi
 
-      # Sync main to dev so Archon worktrees have latest code
-      echo "Syncing main to dev..."
-      git push origin dev 2>/dev/null || true
-      MAIN_SHA=$(git rev-parse origin/main)
-      DEV_SHA=$(git rev-parse origin/dev)
-      if [ "$MAIN_SHA" != "$DEV_SHA" ]; then
-        echo "WARN: main is behind dev — creating sync PR..."
-        gh pr create --base main --head dev --title "chore: sync dev to main" --body "Auto-sync before workflow run" 2>/dev/null || true
-        gh pr merge --merge --admin 2>/dev/null || true
-        git fetch origin
-        echo "PASS: main synced to dev"
-      else
-        echo "PASS: main already in sync with dev"
-      fi
-
       if [ "$PASS" = "true" ]; then
         echo "READY"
       else
@@ -470,28 +469,30 @@ nodes:
       List all issues created with their numbers and titles.
 
   # ═══════════════════════════════════════════════════════════════
-  # Step 12: Create PR to release
+  # Step 12: Create PR to hotfix
   # ═══════════════════════════════════════════════════════════════
 
   - id: create-pr
     depends_on: [file-issues]
     context: fresh
     prompt: |
-      Create a pull request from dev to release.
+      Create a pull request from the current feature branch to hotfix.
 
       Package version: $package.output
       Test results: $test-cycle.output
 
       ## Instructions
 
-      1. Push dev:
+      1. Push the current branch:
          ```bash
-         git push origin dev
+         BRANCH=$(git branch --show-current)
+         git push origin "$BRANCH"
          ```
 
       2. Get commit list:
          ```bash
-         git log --oneline release..dev
+         BRANCH=$(git branch --show-current)
+         git log --oneline hotfix.."$BRANCH"
          ```
 
       3. Get PyPI version:
@@ -526,7 +527,8 @@ nodes:
          in the PR body — GitHub will auto-close the issue when the PR is merged.
          Do NOT manually close the issue — let GitHub handle it via the PR merge.
          ```bash
-         gh pr create --base release --head dev --title "<type>: <description>" --body "$(cat <<'EOF'
+         BRANCH=$(git branch --show-current)
+         gh pr create --base hotfix --head "$BRANCH" --title "<type>: <description>" --body "$(cat <<'EOF'
          Closes #<N>
 
          ## Summary