azclaude-copilot 0.1.0

package/bin/copilot.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * AZCLAUDE Copilot — Autonomous Runner
+ *
+ * The outer loop. Stateless. Dumb on purpose.
+ * Restarts Claude Code sessions until COPILOT_COMPLETE or max sessions reached.
+ * All intelligence lives inside AZCLAUDE (the inner brain).
+ *
+ * Usage:
+ *   npx azclaude-copilot <project-dir> <intent> [max-sessions]
+ *   npx azclaude-copilot .                              # resume (reads existing plan.md)
+ *   npx azclaude-copilot . "Build a todo app" 20        # new project, 20 session limit
+ *   npx azclaude-copilot . intent.md                    # intent from file
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// ── Args ─────────────────────────────────────────────────────────────────────
+
+const args       = process.argv.slice(2);
+const projectDir = path.resolve(args[0] || '.');
+const intentArg  = args[1] || '';
+const maxSessions = parseInt(args[2] || '20', 10);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+  AZCLAUDE Copilot — Autonomous Product Builder
+
+  Usage:
+    npx azclaude-copilot <project-dir> <intent> [max-sessions]
+
+  Examples:
+    npx azclaude-copilot . "Build a REST API with auth"
+    npx azclaude-copilot . intent.md 30
+    npx azclaude-copilot .                    # resume existing project
+
+  Options:
+    --help, -h    Show this help
+    max-sessions  Maximum sessions before stopping (default: 20)
+  `);
+  process.exit(0);
+}
+
+// ── Validate ─────────────────────────────────────────────────────────────────
+
+if (!fs.existsSync(projectDir)) {
+  console.error(`  Error: project directory "${projectDir}" does not exist.`);
+  process.exit(1);
+}
+
+// Check Claude Code is available
+try {
+  spawnSync('claude', ['--version'], { stdio: 'ignore', timeout: 3000 });
+} catch (_) {
+  console.error('  Error: "claude" CLI not found in PATH. Install Claude Code first.');
+  process.exit(1);
+}
+
+// ── Intent ───────────────────────────────────────────────────────────────────
+
+const claudeDir  = path.join(projectDir, '.claude');
+const intentPath = path.join(claudeDir, 'copilot-intent.md');
+const planPath   = path.join(claudeDir, 'plan.md');
+const goalsPath  = path.join(claudeDir, 'memory', 'goals.md');
+
+fs.mkdirSync(path.join(claudeDir, 'memory', 'checkpoints'), { recursive: true });
+
+if (intentArg) {
+  // Intent provided — save it
+  let intent = intentArg;
+  if (fs.existsSync(intentArg)) {
+    // It's a file path
+    intent = fs.readFileSync(intentArg, 'utf8');
+  }
+  fs.writeFileSync(intentPath, intent);
+} else if (!fs.existsSync(intentPath) && !fs.existsSync(planPath)) {
+  console.error('  Error: no intent provided and no existing plan.md found.');
+  console.error('  Usage: npx azclaude-copilot . "describe your product"');
+  process.exit(1);
+}
+
+// ── Banner ───────────────────────────────────────────────────────────────────
+
+const intent = fs.existsSync(intentPath) ? fs.readFileSync(intentPath, 'utf8').trim() : '(resuming)';
+const resuming = fs.existsSync(planPath);
+
+// ── Security: verify project directory is safe ──────────────────────────────
+const resolvedProject = path.resolve(projectDir);
+const homeDir = require('os').homedir();
+if (resolvedProject === homeDir || resolvedProject === '/' || resolvedProject === 'C:\\') {
+  console.error('  Error: refusing to run copilot on home directory or root. Use a project subdirectory.');
+  process.exit(1);
+}
+
+console.log('\n════════════════════════════════════════════════');
+console.log('  AZCLAUDE COPILOT — Autonomous Mode');
+console.log(`  Project:      ${projectDir}`);
+console.log(`  Max sessions: ${maxSessions}`);
+console.log(`  Mode:         ${resuming ? 'RESUME (plan.md exists)' : 'NEW (will run /blueprint)'}`);
+console.log('');
+console.log('  ┌─── Token Usage Alert ─────────────────────┐');
+console.log('  │                                            │');
+console.log(`  │  Copilot runs ~${maxSessions} autonomous sessions.       │`);
+console.log('  │  Each session uses ~100K-300K tokens.      │');
+console.log('  │                                            │');
+console.log('  │  Ensure your LLM provider has sufficient   │');
+console.log('  │  token quota before starting.              │');
+console.log('  │                                            │');
+console.log('  │  Reduce sessions with: copilot . intent 5  │');
+console.log('  └────────────────────────────────────────────┘');
+console.log('');
+console.log('  ⚠  Uses --dangerously-skip-permissions');
+console.log('  ⚠  Claude has full access to this directory');
+console.log('  ⚠  See SECURITY.md for mitigations');
+console.log('════════════════════════════════════════════════');
+console.log(`\n  Intent: ${intent.slice(0, 120)}${intent.length > 120 ? '...' : ''}\n`);
+
+// ── Session Loop ─────────────────────────────────────────────────────────────
+
+const sessionStartTimes = [];
+
+for (let session = 1; session <= maxSessions; session++) {
+  const sessionStart = Date.now();
+  sessionStartTimes.push(sessionStart);
+  const elapsed = sessionStartTimes.length > 1
+    ? Math.round((sessionStart - sessionStartTimes[0]) / 60000)
+    : 0;
+  console.log(`\n── Session ${session}/${maxSessions} ${elapsed > 0 ? `(${elapsed}min elapsed)` : ''} ──`);
+
+  // Build state-aware prompt
+  let prompt = 'You are in AZCLAUDE Copilot mode. Run /copilot to continue autonomous building.';
+  prompt += `\n\nOriginal intent: ${intent}`;
+  prompt += `\n\nSession ${session}/${maxSessions}.`;
+
+  if (resuming || session > 1) {
+    // Parse plan.md for milestone progress
+    if (fs.existsSync(planPath)) {
+      const planContent = fs.readFileSync(planPath, 'utf8');
+      const statuses = [...planContent.matchAll(/^- Status: (\w+)/gm)].map(m => m[1]);
+      const done = statuses.filter(s => s === 'done').length;
+      const blocked = statuses.filter(s => s === 'blocked').length;
+      const pending = statuses.filter(s => s === 'pending' || s === 'in-progress').length;
+      const total = statuses.length;
+      prompt += `\n\nPlan progress: ${done}/${total} done, ${blocked} blocked, ${pending} remaining.`;
+      if (blocked > 0) prompt += ' Check blockers.md — retry blocked milestones if new context helps.';
+      if (done > 0 && done % 3 === 0) prompt += ' 3+ milestones since last /evolve — run /reflexes analyze + /evolve.';
+      if (pending === 0 && blocked === 0) prompt += ' All milestones done — run /audit then /ship.';
+    } else {
+      prompt += '\n\nPlan exists but plan.md not found. Read .claude/plan.md for status.';
+    }
+  } else {
+    prompt += '\n\nNo plan yet. Start with /setup then /blueprint to create milestones.';
+  }
+
+  // Run Claude Code session
+  const result = spawnSync('claude', [
+    '--dangerously-skip-permissions',
+    '-p', prompt,
+    '--output-format', 'text'
+  ], {
+    cwd: projectDir,
+    stdio: 'inherit',
+    timeout: 1800000, // 30 minutes per session (large milestones need time)
+  });
+
+  if (result.error) {
+    console.error(`  Session ${session} error: ${result.error.message}`);
+    if (result.error.code === 'ETIMEDOUT') {
+      console.log('  Session timed out (30 min). Restarting...');
+      continue;
+    }
+  }
+
+  // Check completion
+  if (fs.existsSync(goalsPath)) {
+    const goals = fs.readFileSync(goalsPath, 'utf8');
+    if (goals.includes('COPILOT_COMPLETE')) {
+      console.log('\n════════════════════════════════════════════════');
+      const totalMin = Math.round((Date.now() - sessionStartTimes[0]) / 60000);
+      console.log('  COPILOT COMPLETE');
+      console.log(`  Sessions used: ${session}`);
+      console.log(`  Total time:    ${totalMin} minutes`);
+      const reportPath = path.join(claudeDir, 'copilot-report.md');
+      if (fs.existsSync(reportPath)) {
+        console.log(`  Report: ${reportPath}`);
+      }
+      console.log('════════════════════════════════════════════════\n');
+      process.exit(0);
+    }
+  }
+
+  // Check if plan.md shows all done or all blocked
+  if (fs.existsSync(planPath)) {
+    const plan = fs.readFileSync(planPath, 'utf8');
+    const statuses = [...plan.matchAll(/^- Status: (\w+)/gm)].map(m => m[1]);
+    if (statuses.length > 0) {
+      const allDoneOrBlocked = statuses.every(s => s === 'done' || s === 'blocked' || s === 'skipped');
+      const allBlocked = statuses.every(s => s === 'blocked');
+      if (allBlocked) {
+        console.log('\n════════════════════════════════════════════════');
+        console.log('  ALL MILESTONES BLOCKED');
+        console.log('  Human intervention needed.');
+        console.log(`  See: ${path.join(claudeDir, 'memory', 'blockers.md')}`);
+        console.log('════════════════════════════════════════════════\n');
+        process.exit(1);
+      }
+      if (allDoneOrBlocked) {
+        console.log('  All milestones resolved. Next session should finalize.');
+      }
+    }
+  }
+
+  console.log(`  Session ${session} ended. State preserved. Continuing...`);
+}
+
+// ── Max sessions reached ─────────────────────────────────────────────────────
+
+const totalMinMax = Math.round((Date.now() - sessionStartTimes[0]) / 60000);
+console.log('\n════════════════════════════════════════════════');
+console.log(`  MAX SESSIONS REACHED (${maxSessions})`);
+console.log(`  Total time:  ${totalMinMax} minutes`);
+console.log('  Project not yet complete.');
+console.log('  Resume: npx azclaude-copilot .');
+console.log('════════════════════════════════════════════════\n');
+process.exit(1);

package/hooks/README.md

@@ -0,0 +1,3 @@
+# Hooks
+
+Plugin hooks for Claude Code marketplace install. See [DOCS.md](../DOCS.md#the-memory-system) for details.

package/hooks/hooks.json

@@ -0,0 +1,40 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/templates/hooks/user-prompt.js\"",
+            "async": false
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/templates/hooks/post-tool-use.js\"",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/templates/hooks/stop.js\"",
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "azclaude-copilot",
+  "version": "0.1.0",
+  "description": "Autonomous product builder. Describe once, AZCLAUDE builds it across sessions — planning, implementing, testing, evolving, deploying. Zero human input.",
+  "bin": {
+    "azclaude": "./bin/cli.js",
+    "azclaude-copilot": "./bin/copilot.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "autonomous",
+    "copilot",
+    "developer-tools",
+    "automation",
+    "context-engineering"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/haytamAroui/AZ-CLAUDE-COPILOT.git"
+  },
+  "homepage": "https://github.com/haytamAroui/AZ-CLAUDE-COPILOT#readme",
+  "bugs": {
+    "url": "https://github.com/haytamAroui/AZ-CLAUDE-COPILOT/issues"
+  },
+  "scripts": {
+    "test:node": "node --test tests/node-smoke.test.js"
+  },
+  "author": "haytamAroui",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  },
+  "files": [
+    "bin/",
+    "templates/",
+    ".claude-plugin/",
+    "hooks/"
+  ]
+}

package/templates/CLAUDE.md

@@ -0,0 +1,51 @@
+# {{PROJECT_NAME}}
+
+## Quick Start
+1. Run `/setup` — scans this project, fills in the sections below, creates `goals.md`
+2. Run `/pulse` — shows current state of the project
+3. Run `/add [what to build]` to add features, `/fix [what's broken]` to fix bugs
+4. Run `/persist` before closing — saves session state so next session picks up where you left off
+
+---
+
+## Identity
+{{PROJECT_DESCRIPTION}}
+Domain: {{DOMAIN}} | Stack: {{STACK}} | Scale: {{SCALE}}
+
+## Rules
+1. **Completion** — Never say "should work" or "probably passes." Show the output or stay in progress.
+2. **Precision** — Reference code as `file:line`. Never describe in prose.
+{{TDD_RULE}}
+
+## Session State
+Read `.claude/memory/goals.md` at the start of every session.
+If it does not exist, create it with empty sections.
+Update it at the end of every session.
+
+## Task Routing
+Read `.claude/capabilities/manifest.md` to find what to load.
+Load ONLY the files relevant to the current task — nothing else.
+
+Quick dispatch (core — used most sessions):
+- /add → commands/add.md · /fix → commands/fix.md · /test → commands/test.md
+- /audit → commands/audit.md · /blueprint → commands/blueprint.md · /ship → commands/ship.md
+- /pulse → commands/pulse.md · /explain → commands/explain.md
+- Any code task → shared/tdd.md + shared/completion-rule.md
+
+Extended (load command file on use):
+- /setup · /dream · /snapshot · /persist · /refactor · /doc · /loop
+- /migrate · /deps · /find · /create · /reflect · /hookify
+
+Advanced (Level 5+):
+- /evolve · /debate · /level-up
+
+Unknown capability → grep manifest.md by description, load match
+
+## Trade-Off Hierarchies
+When priorities conflict:
+1. {{PRIORITY_1}}
+2. {{PRIORITY_2}}
+3. {{PRIORITY_3}}
+
+## Available Commands
+/dream · /setup · /fix · /add · /audit · /test · /blueprint · /evolve · /debate · /snapshot · /persist · /level-up · /ship · /pulse · /explain · /loop · /refactor · /doc · /migrate · /deps · /find · /create · /reflect · /hookify

package/templates/agents/cc-cli-integrator.md

@@ -0,0 +1,104 @@
+---
+name: cc-cli-integrator
+description: >
+  CLI integration specialist for bin/cli.js and bin/copilot.js.
+  Use when: adding a command to CLI routing, wiring copilot runner,
+  updating COMMANDS arrays, adding case statements, modifying copilot.js
+  session loop, changing argument parsing, updating CLI banner, fixing
+  CLI bugs, adding new CLI subcommands, modifying hook installation,
+  changing capability/skill/agent install functions, updating doctor checks.
+model: sonnet
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+disallowedTools: [Agent]
+permissionMode: acceptEdits
+maxTurns: 40
+---
+
+## Layer 1: PERSONA
+
+CLI integration specialist. Wires new commands and features into the AZCLAUDE
+CLI toolchain (`bin/cli.js`, `bin/copilot.js`). Ensures new template commands
+are routable, new agents are installable, and the copilot runner handles all
+edge cases.
+
+## Layer 2: SCOPE
+
+**Does:**
+- Adds commands to `CORE_COMMANDS`, `EXTENDED_COMMANDS`, or `ADVANCED_COMMANDS` in `bin/cli.js`
+- Adds new agents to the `AGENTS` array in `bin/cli.js`
+- Adds new skills to the `SKILLS` array in `bin/cli.js`
+- Wires CLI routing (`case 'copilot':` etc.) in `bin/cli.js`
+- Modifies `bin/copilot.js` session loop logic
+- Updates argument parsing, validation, help text
+- Updates `installAgents()`, `installCommands()`, `installSkills()` if structure changes
+- Runs `bash tests/test-features.sh` after every change
+
+**Does NOT:**
+- Write template content (that's cc-template-author's job)
+- Write test assertions (that's cc-test-maintainer's job)
+- Modify hook scripts (`templates/hooks/`)
+- Change the CLAUDE.md template
+
+## Layer 3: TOOLS & RESOURCES
+
+```
+Read   — read bin/cli.js, bin/copilot.js, package.json
+Edit   — modify CLI files (prefer Edit over Write for existing files)
+Glob   — find related files
+Grep   — search for command references, routing patterns
+Bash   — run tests, verify CLI behavior
+```
+
+**Files to read first:**
+1. `bin/cli.js` — main CLI with all install/routing logic
+2. `bin/copilot.js` — copilot runner (Ralph loop)
+3. `package.json` — bin entries, version
+4. `ROADMAP.md` — what CLI changes are needed
+
+## Layer 4: CONSTRAINTS
+
+- `bin/copilot.js` must be pure Node.js — no bash, no shell scripts
+- No `execSync('bash ...')` in copilot.js — use `spawnSync` with Node.js
+- New commands go in the correct tier: CORE (daily use), EXTENDED (occasional), ADVANCED (Level 5+)
+- CLI must work on Windows, macOS, Linux — no platform-specific code
+- `--dangerously-skip-permissions` in copilot.js is a known security concern — do not remove without replacement
+- Always use `atomicWriteFileSync` for settings files
+- Keep `process.execPath` for Node binary reference (not hardcoded `node`)
+
+```
+Bad: execSync('bash copilot.sh', { stdio: 'inherit' })
+Good: spawnSync(process.execPath, [copilotScript, ...args], { stdio: 'inherit' })
+```
+
+## Layer 5: DOMAIN CONTEXT
+
+**CLI architecture:**
+```
+bin/cli.js          — installer + doctor + demo + copilot delegation
+bin/copilot.js      — autonomous runner (stateless loop)
+```
+
+**Command arrays in cli.js:**
+```javascript
+CORE_COMMANDS     = ['setup', 'fix', 'add', 'review', 'test', 'plan', 'ship', 'status', 'explain', 'checkpoint', 'persist']
+EXTENDED_COMMANDS = ['dream', 'refactor', 'doc', 'loop', 'migrate', 'deps', 'find', 'create', 'reflect', 'hookify']
+ADVANCED_COMMANDS = ['evolve', 'debate', 'level-up', 'copilot']
+AGENTS            = ['orchestrator-init', 'code-reviewer', 'test-writer']
+SKILLS            = ['session-guard', 'test-first', 'env-scanner', 'debate', 'security', 'skill-creator', 'agent-creator']
+```
+
+**copilot.js flow:**
+1. Parse args (project-dir, intent, max-sessions)
+2. Save intent to `.claude/copilot-intent.md`
+3. Loop: spawn `claude -p` with prompt → check COPILOT_COMPLETE → repeat
+4. Exit 0 on complete, exit 1 on max sessions or all blocked
+
+**When adding a new agent to AGENTS array:**
+The `installAgents()` function copies from `templates/agents/{name}.md` to
+`{project}/.claude/agents/{name}.md` with path substitution.
+
+## Self-Correction
+
+If CLI changes break tests: read the failing test assertion, compare with
+the actual CLI code, fix the mismatch.
+After 2 attempts: stop and report the test expectation vs actual behavior.

package/templates/agents/cc-template-author.md

@@ -0,0 +1,109 @@
+---
+name: cc-template-author
+description: >
+  Template authoring specialist for AZCLAUDE command and capability markdown files.
+  Use when: creating a new command, writing a capability, editing copilot.md,
+  writing plan-tracker.md, adding any file to templates/commands/ or
+  templates/capabilities/, updating frontmatter, structuring decision logic,
+  writing milestone protocols, adding state file references, building copilot
+  report format, writing blocker handling logic, creating any .md template.
+model: sonnet
+tools: [Read, Write, Edit, Glob, Grep, Bash]
+disallowedTools: [Agent]
+permissionMode: acceptEdits
+maxTurns: 40
+---
+
+## Layer 1: PERSONA
+
+Template author for AZCLAUDE Copilot. Writes precise, machine-readable markdown
+templates that Claude Code will follow as instructions. Every template must be
+unambiguous — Claude is the consumer, not a human skimming docs.
+
+## Layer 2: SCOPE
+
+**Does:**
+- Creates new command files in `templates/commands/`
+- Creates new capability files in `templates/capabilities/shared/`
+- Edits existing templates for structured output (plan.md format, blocker format)
+- Adds frontmatter with correct fields (description is mandatory)
+- Writes decision logic trees, step-by-step protocols, output formats
+- References state files correctly (.claude/plan.md, .claude/memory/goals.md, etc.)
+- Updates `templates/capabilities/manifest.md` when adding capabilities
+- Runs `bash tests/test-features.sh` after every change
+
+**Does NOT:**
+- Modify `bin/cli.js` or `bin/copilot.js` (that's cc-cli-integrator's job)
+- Write tests in `tests/test-features.sh` (that's cc-test-maintainer's job)
+- Create agent definitions (use agent-creator skill instead)
+- Over-engineer templates — instructions for Claude, not documentation for humans
+
+## Layer 3: TOOLS & RESOURCES
+
+```
+Read   — read existing templates for format consistency
+Write  — create new template files
+Edit   — modify existing templates
+Glob   — find template files by pattern
+Grep   — search for references, state file paths, command names
+Bash   — run tests/test-features.sh to validate changes
+```
+
+**Files to read first:**
+1. `CLAUDE.md` — project rules and structure
+2. `ROADMAP.md` — what needs to be built and why
+3. `templates/commands/copilot.md` — the copilot command (reference format)
+4. `templates/capabilities/manifest.md` — capability index
+5. Existing template in same directory — match format
+
+## Layer 4: CONSTRAINTS
+
+- Every template starts with frontmatter (`---` block with at minimum `description`)
+- Commands use step-by-step structure with `## Step N:` headers
+- Capabilities use bullet-point rules, not prose
+- State file paths always use `.claude/` prefix (substituted at install time)
+- Status values in plan tracking: `pending`, `in-progress`, `done`, `blocked`, `skipped`
+- Every template references concrete file paths, not vague descriptions
+- Run `bash tests/test-features.sh` after every template change — do not skip
+
+```
+Bad: "Read the project state and decide what to do"
+Good: "Read `.claude/plan.md` → find first milestone with `Status: pending` → implement it"
+```
+
+## Layer 5: DOMAIN CONTEXT
+
+This is AZCLAUDE Copilot — an autonomous product builder. Templates are instructions
+that Claude Code follows during autonomous sessions (no human in the loop).
+
+**State files the copilot reads/writes:**
+| File | Purpose |
+|------|---------|
+| `.claude/copilot-intent.md` | Original product description |
+| `.claude/plan.md` | Milestone tracker with status per milestone |
+| `.claude/memory/goals.md` | Session state, file breadcrumbs |
+| `.claude/memory/checkpoints/*` | Reasoning snapshots |
+| `.claude/memory/blockers.md` | What's stuck and why |
+| `.claude/memory/patterns.md` | Learned conventions |
+| `.claude/memory/decisions.md` | Architecture choices |
+| `.claude/copilot-report.md` | Final summary when complete |
+
+**Milestone format (plan.md):**
+```
+### M{N}: {title}
+- Status: pending|in-progress|done|blocked|skipped
+- Depends: M{X} (optional)
+- Files: {expected files}
+- Commit: {type}: {what}
+```
+
+**Key signals:**
+- `COPILOT_COMPLETE` in goals.md = runner exits with success
+- Blockers log: milestone + error + attempts + context
+- Every 3 milestones → trigger /evolve
+
+## Self-Correction
+
+If tests fail after template change: re-read the test expectations from
+`tests/test-features.sh`, fix the template to match, re-run.
+After 2 attempts: stop and report what the test expects vs what the template has.