legion-cc 0.1.0

package/bin/lib/state.cjs

@@ -0,0 +1,280 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { currentTimestamp } = require('./core.cjs');
+
+// ─── STATE.md Parsing ────────────────────────────────────────────────────────
+
+/**
+ * Parse STATE.md into a structured object.
+ *
+ * @param {string} planningDir - Absolute path to `.planning/legion/`
+ * @returns {object|null} Parsed state, or null if STATE.md doesn't exist
+ */
+function loadState(planningDir) {
+  const statePath = path.join(planningDir, 'STATE.md');
+  if (!fs.existsSync(statePath)) return null;
+
+  const raw = fs.readFileSync(statePath, 'utf8');
+  const state = {
+    project: {
+      domain: '',
+      lastActivity: '',
+    },
+    currentWork: {
+      pipeline: '',
+      stage: '',
+      input: '',
+      lastCompleted: '',
+      next: '',
+    },
+    taskHistory: [],
+  };
+
+  const lines = raw.split('\n');
+  let section = '';
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Detect section headers
+    if (line.startsWith('## Project')) {
+      section = 'project';
+      continue;
+    }
+    if (line.startsWith('## Current Work')) {
+      section = 'currentWork';
+      continue;
+    }
+    if (line.startsWith('## Task History')) {
+      section = 'taskHistory';
+      continue;
+    }
+
+    if (section === 'project') {
+      const domainMatch = line.match(/^Domain:\s*(.+)$/);
+      if (domainMatch) state.project.domain = domainMatch[1].trim();
+
+      const activityMatch = line.match(/^Last activity:\s*(.+)$/);
+      if (activityMatch) state.project.lastActivity = activityMatch[1].trim();
+    }
+
+    if (section === 'currentWork') {
+      const pipelineMatch = line.match(/^Pipeline:\s*(.+)$/);
+      if (pipelineMatch) state.currentWork.pipeline = pipelineMatch[1].trim();
+
+      const stageMatch = line.match(/^Stage:\s*(.+)$/);
+      if (stageMatch) state.currentWork.stage = stageMatch[1].trim();
+
+      const inputMatch = line.match(/^Input:\s*(.+)$/);
+      if (inputMatch) state.currentWork.input = inputMatch[1].trim();
+
+      const lastMatch = line.match(/^Last completed:\s*(.+)$/);
+      if (lastMatch) state.currentWork.lastCompleted = lastMatch[1].trim();
+
+      const nextMatch = line.match(/^Next:\s*(.+)$/);
+      if (nextMatch) state.currentWork.next = nextMatch[1].trim();
+    }
+
+    if (section === 'taskHistory') {
+      // Parse table rows (skip header and separator lines)
+      const rowMatch = line.match(/^\|\s*(\d+)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|\s*(.+?)\s*\|$/);
+      if (rowMatch) {
+        state.taskHistory.push({
+          num: parseInt(rowMatch[1], 10),
+          type: rowMatch[2].trim(),
+          description: rowMatch[3].trim(),
+          date: rowMatch[4].trim(),
+          status: rowMatch[5].trim(),
+          artifact: rowMatch[6].trim(),
+        });
+      }
+    }
+  }
+
+  return state;
+}
+
+// ─── STATE.md Serialization ──────────────────────────────────────────────────
+
+/**
+ * Write a structured state object back to STATE.md.
+ *
+ * @param {string} planningDir - Absolute path to `.planning/legion/`
+ * @param {object} stateObj - State object (same shape as loadState output)
+ */
+function saveState(planningDir, stateObj) {
+  const statePath = path.join(planningDir, 'STATE.md');
+
+  const lines = [];
+  lines.push('# Legion State');
+  lines.push('');
+  lines.push('## Project');
+  lines.push(`Domain: ${stateObj.project.domain}`);
+  lines.push(`Last activity: ${stateObj.project.lastActivity}`);
+  lines.push('');
+  lines.push('## Current Work');
+  lines.push(`Pipeline: ${stateObj.currentWork.pipeline}`);
+  lines.push(`Stage: ${stateObj.currentWork.stage}`);
+  lines.push(`Input: ${stateObj.currentWork.input}`);
+  lines.push(`Last completed: ${stateObj.currentWork.lastCompleted}`);
+  lines.push(`Next: ${stateObj.currentWork.next}`);
+  lines.push('');
+  lines.push('## Task History');
+  lines.push('');
+  lines.push('| # | Type | Description | Date | Status | Artifact |');
+  lines.push('|---|------|-------------|------|--------|----------|');
+
+  if (stateObj.taskHistory && stateObj.taskHistory.length > 0) {
+    for (const task of stateObj.taskHistory) {
+      lines.push(`| ${task.num} | ${task.type} | ${task.description} | ${task.date} | ${task.status} | ${task.artifact} |`);
+    }
+  }
+
+  lines.push('');
+
+  if (!fs.existsSync(planningDir)) {
+    fs.mkdirSync(planningDir, { recursive: true });
+  }
+
+  fs.writeFileSync(statePath, lines.join('\n'), 'utf8');
+}
+
+// ─── Field Update ────────────────────────────────────────────────────────────
+
+/**
+ * Update a single field in STATE.md.
+ * Supports dot-notation for nested fields: "project.domain", "currentWork.stage", etc.
+ *
+ * @param {string} planningDir
+ * @param {string} field - Dot-notation field path
+ * @param {string} value - New value
+ */
+function updateField(planningDir, field, value) {
+  const state = loadState(planningDir);
+  if (!state) {
+    throw new Error('STATE.md not found in ' + planningDir);
+  }
+
+  const parts = field.split('.');
+  let target = state;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (target[parts[i]] === undefined) {
+      throw new Error(`Unknown field path: ${field}`);
+    }
+    target = target[parts[i]];
+  }
+
+  const lastKey = parts[parts.length - 1];
+  if (target[lastKey] === undefined) {
+    throw new Error(`Unknown field: ${field}`);
+  }
+
+  target[lastKey] = value;
+  saveState(planningDir, state);
+}
+
+// ─── Task Record ─────────────────────────────────────────────────────────────
+
+/**
+ * Append a new task record to the task history in STATE.md.
+ *
+ * @param {string} planningDir
+ * @param {object} record
+ * @param {string} record.type - Task type (architect, plan, execute, review)
+ * @param {string} record.description - Short description
+ * @param {string} record.status - Status (done, in-progress, blocked, pending)
+ * @param {string} [record.artifact] - Path to related artifact file
+ */
+function addTaskRecord(planningDir, record) {
+  const state = loadState(planningDir);
+  if (!state) {
+    throw new Error('STATE.md not found in ' + planningDir);
+  }
+
+  const nextNum = state.taskHistory.length > 0
+    ? Math.max(...state.taskHistory.map(t => t.num)) + 1
+    : 1;
+
+  state.taskHistory.push({
+    num: nextNum,
+    type: record.type || 'unknown',
+    description: record.description || '',
+    date: currentTimestamp('date'),
+    status: record.status || 'pending',
+    artifact: record.artifact || '-',
+  });
+
+  // Update last activity
+  state.project.lastActivity = `${currentTimestamp('date')} \u2014 ${record.description}`;
+
+  saveState(planningDir, state);
+}
+
+// ─── Current Work ────────────────────────────────────────────────────────────
+
+/**
+ * Update the "Current Work" section of STATE.md.
+ *
+ * @param {string} planningDir
+ * @param {object} work
+ * @param {string} [work.stage] - Current pipeline stage
+ * @param {string} [work.input] - Input artifact path
+ * @param {string} [work.next] - Next action slug
+ */
+function setCurrentWork(planningDir, work) {
+  const state = loadState(planningDir);
+  if (!state) {
+    throw new Error('STATE.md not found in ' + planningDir);
+  }
+
+  if (work.stage !== undefined) state.currentWork.stage = work.stage;
+  if (work.input !== undefined) state.currentWork.input = work.input;
+  if (work.next !== undefined) state.currentWork.next = work.next;
+
+  saveState(planningDir, state);
+}
+
+// ─── Initialization ──────────────────────────────────────────────────────────
+
+/**
+ * Create an initial STATE.md in the given planning directory.
+ *
+ * @param {string} planningDir
+ * @param {string} domain - Domain name (e.g. 'devops')
+ */
+function initState(planningDir, domain) {
+  if (!fs.existsSync(planningDir)) {
+    fs.mkdirSync(planningDir, { recursive: true });
+  }
+
+  const state = {
+    project: {
+      domain: domain || 'devops',
+      lastActivity: `${currentTimestamp('date')} \u2014 initialized`,
+    },
+    currentWork: {
+      pipeline: 'architect -> plan -> execute -> review',
+      stage: 'architect',
+      input: '-',
+      lastCompleted: '-',
+      next: `/legion:${domain || 'devops'}:architect`,
+    },
+    taskHistory: [],
+  };
+
+  saveState(planningDir, state);
+  return state;
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  loadState,
+  saveState,
+  updateField,
+  addTaskRecord,
+  setCurrentWork,
+  initState,
+};

package/commands/legion/devops/architect.md

@@ -0,0 +1,44 @@
+---
+name: legion:devops:architect
+description: "Design infrastructure architecture with devops-architect agent — creates architecture documents in .planning/legion/devops/"
+argument-hint: "<architecture task description>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - WebSearch
+  - WebFetch
+---
+
+# Legion DevOps Architect
+
+Invoke the devops-architect agent to design infrastructure architecture.
+
+## Execution
+
+Follow the workflow at @~/.claude/legion/workflows/devops/architect.md
+
+### Quick Reference
+
+**Initialization**: @~/.claude/legion/workflows/core/init.md
+**Context Loading**: @~/.claude/legion/workflows/core/context-load.md
+**Completion**: @~/.claude/legion/workflows/core/completion.md
+
+### Agent Details
+
+- **Agent**: devops-architect
+- **subagent_type**: devops-architect
+- **Model**: opus
+- **Role**: Senior/Lead DevOps Architect — designs reliable, scalable, secure infrastructure
+
+### Pipeline Position
+
+```
+[architect] → plan → execute → review
+```
+
+After completion, suggest: `/legion:devops:plan`

package/commands/legion/devops/build.md

@@ -0,0 +1,52 @@
+---
+name: legion:devops:build
+description: "Scaffold project codebase and .codebase/ documentation with codebase-builder agent"
+argument-hint: "[path-to-architecture]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - WebSearch
+  - WebFetch
+---
+
+# Legion DevOps Build
+
+Invoke the codebase-builder agent to scaffold project structure and create .codebase/ documentation.
+
+## Execution
+
+Follow the workflow at @~/.claude/legion/workflows/devops/build.md
+
+### Quick Reference
+
+**Initialization**: @~/.claude/legion/workflows/core/init.md
+**Context Loading**: @~/.claude/legion/workflows/core/context-load.md
+**Completion**: @~/.claude/legion/workflows/core/completion.md
+
+### Agent Details
+
+- **Agent**: codebase-builder
+- **subagent_type**: codebase-builder
+- **Model**: opus
+- **Role**: Elite Codebase Builder — scaffolds complete project foundations
+
+### Input
+
+Optional architecture/plan input:
+1. Check $ARGUMENTS for explicit path to architecture doc
+2. Can also use latest architect + planner outputs from STATE.md
+3. Can work without input — will inspect existing codebase and create .codebase/ docs
+
+### Pipeline Position
+
+Standalone command or first step for new projects:
+```
+[build] → architect → plan → execute → review
+```
+
+After completion, suggest: `/legion:devops:architect` if architecture needed

package/commands/legion/devops/cycle.md

@@ -0,0 +1,52 @@
+---
+name: legion:devops:cycle
+description: "Full DevOps pipeline — architect → plan → execute → review with checkpoints between stages"
+argument-hint: "<task description>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - WebSearch
+  - WebFetch
+---
+
+# Legion DevOps Cycle
+
+Run the complete DevOps pipeline in one command with approval checkpoints.
+
+## Execution
+
+Follow the workflow at @~/.claude/legion/workflows/devops/cycle.md
+
+### Quick Reference
+
+**Initialization**: @~/.claude/legion/workflows/core/init.md
+**Context Loading**: @~/.claude/legion/workflows/core/context-load.md
+**Completion**: @~/.claude/legion/workflows/core/completion.md
+**Agent Map**: @~/.claude/legion/references/devops/agent-map.md
+
+### Pipeline Stages
+
+| Stage | Agent | Model | Checkpoint |
+|-------|-------|-------|------------|
+| 1. Architect | devops-architect | opus | ✓ User approval required |
+| 2. Plan | delivery-planner | sonnet | ✓ User approval required |
+| 3. Execute | infra-executor | opus | — |
+| 4. Review | devops-architect | sonnet | — |
+
+### Checkpoints
+
+After stages 1 (architect) and 2 (plan), the workflow pauses to show the output summary and asks the user to confirm before proceeding. User can:
+- **Approve** — continue to next stage
+- **Revise** — re-run the stage with feedback
+- **Stop** — save progress and exit (resume with `/legion:resume`)
+
+### Pipeline Flow
+
+```
+[architect] ──checkpoint──► [plan] ──checkpoint──► [execute] ──► [review]
+```

package/commands/legion/devops/execute.md

@@ -0,0 +1,52 @@
+---
+name: legion:devops:execute
+description: "Execute infrastructure plan with infra-executor agent — implements tasks from delivery plan"
+argument-hint: "[path-to-plan] [--task T1]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - WebSearch
+  - WebFetch
+---
+
+# Legion DevOps Execute
+
+Invoke the infra-executor agent to implement infrastructure changes from a plan.
+
+## Execution
+
+Follow the workflow at @~/.claude/legion/workflows/devops/execute.md
+
+### Quick Reference
+
+**Initialization**: @~/.claude/legion/workflows/core/init.md
+**Context Loading**: @~/.claude/legion/workflows/core/context-load.md
+**Completion**: @~/.claude/legion/workflows/core/completion.md
+
+### Agent Details
+
+- **Agent**: infra-executor
+- **subagent_type**: infra-executor
+- **Model**: opus
+- **Role**: Elite Infrastructure Execution Specialist — implements plans with surgical precision
+
+### Input
+
+Requires plan output. Will:
+1. Check $ARGUMENTS for explicit path to plan
+2. If `--task T1` provided, execute only that specific task
+3. If not provided, find latest plan artifact from STATE.md
+4. If no plan found, warn and ask user
+
+### Pipeline Position
+
+```
+architect → plan → [execute] → review
+```
+
+After completion, suggest: `/legion:devops:review`

package/commands/legion/devops/plan.md

@@ -0,0 +1,51 @@
+---
+name: legion:devops:plan
+description: "Decompose architecture into executable implementation plan with delivery-planner agent"
+argument-hint: "[path-to-architect-output]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - WebSearch
+  - WebFetch
+---
+
+# Legion DevOps Plan
+
+Invoke the delivery-planner agent to decompose an architecture into executable tasks.
+
+## Execution
+
+Follow the workflow at @~/.claude/legion/workflows/devops/plan.md
+
+### Quick Reference
+
+**Initialization**: @~/.claude/legion/workflows/core/init.md
+**Context Loading**: @~/.claude/legion/workflows/core/context-load.md
+**Completion**: @~/.claude/legion/workflows/core/completion.md
+
+### Agent Details
+
+- **Agent**: delivery-planner
+- **subagent_type**: delivery-planner
+- **Model**: sonnet
+- **Role**: Senior Delivery Planner — transforms architecture into phased implementation plans
+
+### Input
+
+Requires architect output. Will:
+1. Check $ARGUMENTS for explicit path to architect output
+2. If not provided, find latest architect artifact from STATE.md
+3. If no architect output found, warn and ask user
+
+### Pipeline Position
+
+```
+architect → [plan] → execute → review
+```
+
+After completion, suggest: `/legion:devops:execute`

package/commands/legion/devops/quick.md

@@ -0,0 +1,45 @@
+---
+name: legion:devops:quick
+description: "Fast context-aware DevOps task execution — reads .codebase/, identifies work type, dispatches to the right agent (architect/planner/executor/builder)"
+argument-hint: "<task description>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - WebSearch
+  - WebFetch
+---
+
+# Legion DevOps Quick
+
+Fast context-aware execution for DevOps tasks. Reads project context, classifies the task, and dispatches to the appropriate agent.
+
+## Execution
+
+Follow the workflow at @~/.claude/legion/workflows/devops/quick.md
+
+### Quick Reference
+
+**Initialization**: @~/.claude/legion/workflows/core/init.md
+**Context Loading**: @~/.claude/legion/workflows/core/context-load.md
+**Completion**: @~/.claude/legion/workflows/core/completion.md
+**Agent Map**: @~/.claude/legion/references/devops/agent-map.md
+
+### Agent Routing
+
+| Task Type | Agent | subagent_type | Model |
+|-----------|-------|---------------|-------|
+| Architecture/design | devops-architect | devops-architect | opus |
+| Planning/decomposition | delivery-planner | delivery-planner | sonnet |
+| Infrastructure execution | infra-executor | infra-executor | opus |
+| Codebase scaffolding | codebase-builder | codebase-builder | opus |
+
+### Key Rules
+- ALWAYS read .codebase/ before starting work
+- If task is unclear, ASK the user — don't guess
+- Pass full context summary to the spawned agent
+- Update STATE.md after completion

package/commands/legion/devops/review.md

@@ -0,0 +1,52 @@
+---
+name: legion:devops:review
+description: "Review infrastructure architecture or executed changes against architectural intent"
+argument-hint: "[path-to-review-target]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - WebSearch
+  - WebFetch
+---
+
+# Legion DevOps Review
+
+Invoke the devops-architect agent in review mode to validate implemented changes.
+
+## Execution
+
+Follow the workflow at @~/.claude/legion/workflows/devops/review.md
+
+### Quick Reference
+
+**Initialization**: @~/.claude/legion/workflows/core/init.md
+**Context Loading**: @~/.claude/legion/workflows/core/context-load.md
+**Completion**: @~/.claude/legion/workflows/core/completion.md
+
+### Agent Details
+
+- **Agent**: devops-architect (in review mode)
+- **subagent_type**: devops-architect
+- **Model**: sonnet
+- **Role**: Architecture Reviewer — validates changes against design intent
+
+### Input
+
+Review target resolution:
+1. Check $ARGUMENTS for explicit path to review
+2. If not provided, find latest execution artifact from STATE.md
+3. Also loads original architect output for comparison
+4. Can review arbitrary code/config when path provided
+
+### Pipeline Position
+
+```
+architect → plan → execute → [review]
+```
+
+Pipeline terminal step. After completion, suggest next cycle or standalone tasks.

package/commands/legion/resume.md

@@ -0,0 +1,52 @@
+---
+name: legion:resume
+description: "Resume work from previous Legion session with full context restoration"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - Task
+---
+
+# Legion Resume
+
+Restore context from a previous session and continue where you left off.
+
+## Execution
+
+Follow the workflow at @~/.claude/legion/workflows/resume.md
+
+### Process
+
+1. Run `node ~/.claude/legion/bin/legion-tools.cjs init resume`
+2. Read `.planning/legion/STATE.md`
+3. Read the latest session record from `.planning/legion/sessions/`
+4. Load context: @~/.claude/legion/workflows/core/context-load.md
+5. Determine where work stopped:
+   - Check `currentWork.stage` in STATE.md
+   - Find the latest artifact
+   - Identify incomplete pipeline stages
+6. Display restoration summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ LEGION ► RESUME
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Restoring context...
+
+✓ STATE.md loaded
+✓ Last session: {date}
+✓ Domain: {domain}
+✓ Pipeline: {pipeline position}
+✓ Last completed: {last task}
+
+◆ Ready to continue.
+
+► Next: /legion:devops:{next_action}
+  {description of what's next}
+```
+
+7. Route to the appropriate next command based on pipeline position