agile-context-engineering 0.3.0 → 0.5.0

package/skills/help/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: help
+description: Check project initialization status and suggest next steps
+argument-hint: ""
+disable-model-invocation: false
+allowed-tools: Read, Bash, Write, AskUserQuestion
+model: sonnet
+effort: medium
+---
+
+# Help
+
+Interactive state-checker, settings configurator, and guided router for project initialization. Detects which ACE documents exist, ensures settings are configured (including GitHub Project integration), displays a status dashboard, and offers to run missing setup commands.
+
+## When to Use
+
+- At any time to check which ACE documents exist and what to do next
+- At the start of a new project to see the initialization checklist
+- Returning to a project and want to check initialization status
+- Unsure which ACE command to run next
+
+## Input
+
+No parameters required.
+
+## Supporting Resources
+
+Read ALL of these before starting the workflow:
+
+- **Workflow**: Read [workflow.xml](workflow.xml) -- complete orchestration process with all steps
+- **Questioning guide**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/questioning.xml` -- deep questioning techniques
+- **UI formatting**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md` -- ACE output formatting rules
+
+## Process
+
+Execute the help workflow from [workflow.xml](workflow.xml) end-to-end.
+This is a lightweight state-check and routing workflow.
+
+CRITICAL MANDATORY STEP -- DO NOT SKIP:
+Before displaying the status dashboard, run:
+```bash
+node "${CLAUDE_SKILL_DIR}/script.js" sync-agent-teams --raw
+```
+Then you MUST use `AskUserQuestion` to ask the user whether they want to
+enable or disable Claude Code Agent Teams (experimental feature).
+This step is NOT optional. You MUST present this question every time.
+
+When the user chooses to enable or disable Agent Teams, you MUST run the
+bash command -- NEVER directly edit .ace/settings.json or .claude/settings.json:
+```bash
+node "${CLAUDE_SKILL_DIR}/script.js" write-agent-teams true
+```
+or
+```bash
+node "${CLAUDE_SKILL_DIR}/script.js" write-agent-teams false
+```
+The write-agent-teams command updates BOTH .ace/settings.json AND .claude/settings.json.
+Direct file edits will cause the two files to go out of sync.
+
+## Artifacts
+
+- `.ace/settings.json` (created on first run if missing)
+
+## Next Steps
+
+**Specialized commands for each document:**
+- `/ace:plan-product-vision` -- Create or update the product vision
+- `/ace:map-system` -- Map codebase structure, architecture, and testing framework
+- `/ace:init-coding-standards` -- Generate tailored coding standards

package/skills/help/script.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+
+/**
+ * help skill script — Entry point for all ace-tools operations
+ * needed by the help skill.
+ *
+ * Subcommands:
+ *   init                             Environment detection for help workflow
+ *   ensure-settings                  Create .ace/settings.json with defaults if missing
+ *   setup-github                     Detect gh CLI, repo, and list GitHub Projects
+ *   write-github-settings            Write GitHub Project settings (key=value args)
+ *   sync-agent-teams                 Sync agent_teams from runtime settings to .ace/settings.json
+ *   write-agent-teams <true|false>   Enable/disable agent teams in ACE + runtime settings
+ *   verify-path-exists <path>        Check file/directory existence
+ *
+ * Usage: node script.js <subcommand> [args] [--raw]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  loadConfig, pathExists, resolveModel,
+  detectBrownfieldStatus, loadSettings, writeSettings,
+  output, error,
+} = require('../../shared/lib/ace-core');
+
+// ─── Runtime Config Dir ─────────────────────────────────────────────────────
+
+/**
+ * Detect the runtime config directory name.
+ * In the plugin context, the script lives at:
+ *   <base>/<config-dir>/skills/help/script.js
+ * Default to '.claude' since the plugin always runs in Claude Code.
+ */
+function getRuntimeConfigDirName() {
+  try {
+    const skillDir = __dirname;                // <base>/<config-dir>/skills/help
+    const skillsDir = path.dirname(skillDir);  // <base>/<config-dir>/skills
+    const configDir = path.dirname(skillsDir); // <base>/<config-dir>
+    const dirName = path.basename(configDir);
+    if (dirName === '.opencode' || dirName === '.claude') {
+      return dirName;
+    }
+  } catch {}
+  return '.claude';
+}
+
+const RUNTIME_CONFIG_DIR = getRuntimeConfigDirName();
+
+// ─── CLI Dispatch ────────────────────────────────────────────────────────────
+
+const cwd = process.cwd();
+const args = process.argv.slice(2);
+const raw = args.includes('--raw');
+const cmd = args[0];
+
+switch (cmd) {
+  case 'init':
+    cmdInit(cwd, raw);
+    break;
+  case 'ensure-settings':
+    cmdEnsureSettings(cwd, raw);
+    break;
+  case 'setup-github':
+    cmdSetupGithubProject(cwd, raw);
+    break;
+  case 'write-github-settings':
+    cmdWriteGithubSettings(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  case 'sync-agent-teams':
+    cmdSyncAgentTeams(cwd, raw);
+    break;
+  case 'write-agent-teams':
+    cmdWriteAgentTeamsSetting(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  case 'verify-path-exists': {
+    const targetPath = args[1];
+    if (!targetPath) error('path required for verify-path-exists');
+    const exists = pathExists(cwd, targetPath);
+    output({ exists, path: targetPath }, raw, exists ? 'true' : 'false');
+    break;
+  }
+  default:
+    error(`Unknown command: ${cmd}\nAvailable: init, ensure-settings, setup-github, write-github-settings, sync-agent-teams, write-agent-teams, verify-path-exists`);
+}
+
+// ─── Init: Help ─────────────────────────────────────────────────────────────
+
+/**
+ * Environment detection for the help workflow (project status dashboard).
+ * Detects: git, gh CLI, brownfield status, wiki state, product artifacts.
+ */
+function cmdInit(cwd, raw) {
+  const config = loadConfig(cwd);
+  const brownfield = detectBrownfieldStatus(cwd);
+
+  const result = {
+    // Models (pre-resolved so workflows know which model to spawn each agent with)
+    product_owner_model: resolveModel(cwd, 'ace-product-owner'),
+    researcher_model: resolveModel(cwd, 'ace-project-researcher'),
+    synthesizer_model: resolveModel(cwd, 'ace-research-synthesizer'),
+
+    // Config
+    commit_docs: config.commit_docs,
+
+    // Existing state
+    has_product_vision: pathExists(cwd, '.docs/product/product-vision.md'),
+    has_system_architecture: pathExists(cwd, '.docs/wiki/system-wide/system-architecture.md'),
+    has_system_structure: pathExists(cwd, '.docs/wiki/system-wide/system-structure.md'),
+    has_coding_standards: pathExists(cwd, '.docs/wiki/system-wide/coding-standards.md'),
+    has_testing_framework: pathExists(cwd, '.docs/wiki/system-wide/testing-framework.md'),
+    project_exists: pathExists(cwd, '.docs/product/product-vision.md'),
+    has_codebase_map: pathExists(cwd, '.ace/codebase'),
+    planning_exists: pathExists(cwd, '.ace'),
+
+    // Brownfield detection
+    ...brownfield,
+    needs_codebase_map: brownfield.is_brownfield && !pathExists(cwd, '.ace/codebase'),
+
+    // Git state
+    has_git: pathExists(cwd, '.git'),
+
+    // GitHub CLI
+    has_gh_cli: (() => {
+      try {
+        const { execSync } = require('child_process');
+        execSync('gh --version', { stdio: 'pipe' });
+        return true;
+      } catch { return false; }
+    })(),
+  };
+
+  output(result, raw);
+}
+
+// ─── Ensure Settings ────────────────────────────────────────────────────────
+
+function cmdEnsureSettings(cwd, raw) {
+  const settingsPath = path.join(cwd, '.ace', 'settings.json');
+  const alreadyExists = pathExists(cwd, '.ace/settings.json');
+
+  if (!alreadyExists) {
+    const SETTINGS_DEFAULTS = {
+      model_profile: 'balanced',
+      commit_docs: true,
+      agent_teams: false,
+      github_project: {
+        enabled: false,
+        gh_installed: false,
+        repo: '',
+        project_number: null,
+        owner: '',
+      },
+    };
+    const defaults = JSON.parse(JSON.stringify(SETTINGS_DEFAULTS));
+    writeSettings(cwd, defaults);
+    output({ created: true, path: settingsPath, settings: defaults }, raw);
+  } else {
+    const settings = loadSettings(cwd);
+    output({ created: false, path: settingsPath, settings }, raw);
+  }
+}
+
+// ─── Setup GitHub Project ───────────────────────────────────────────────────
+
+function cmdSetupGithubProject(cwd, raw) {
+  const { execSync } = require('child_process');
+  const settings = loadSettings(cwd);
+
+  // Detect gh CLI
+  let ghInstalled = false;
+  try {
+    execSync('gh --version', { stdio: 'pipe' });
+    ghInstalled = true;
+  } catch {}
+
+  // Detect repo
+  let repo = '';
+  let owner = '';
+  if (ghInstalled) {
+    try {
+      repo = execSync('gh repo view --json nameWithOwner -q .nameWithOwner', {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+      }).trim();
+      owner = repo.split('/')[0] || '';
+    } catch {}
+  }
+
+  // List projects
+  let projects = [];
+  if (ghInstalled && owner) {
+    try {
+      const projectsJson = execSync(`gh project list --owner ${owner} --limit 10 --format json`, {
+        cwd,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        encoding: 'utf-8',
+      }).trim();
+      const parsed = JSON.parse(projectsJson);
+      projects = (parsed.projects || parsed || []).map(p => ({
+        number: p.number,
+        title: p.title,
+      }));
+    } catch {}
+  }
+
+  output({
+    gh_installed: ghInstalled,
+    repo,
+    owner,
+    projects,
+    current_settings: settings.github_project,
+  }, raw);
+}
+
+// ─── Write GitHub Settings ──────────────────────────────────────────────────
+
+function cmdWriteGithubSettings(cwd, raw, extraArgs) {
+  const settings = loadSettings(cwd);
+
+  for (const arg of extraArgs) {
+    const eqIndex = arg.indexOf('=');
+    if (eqIndex === -1) continue;
+    const key = arg.substring(0, eqIndex);
+    const value = arg.substring(eqIndex + 1);
+
+    switch (key) {
+      case 'enabled':
+        settings.github_project.enabled = value === 'true';
+        break;
+      case 'gh_installed':
+        settings.github_project.gh_installed = value === 'true';
+        break;
+      case 'repo':
+        settings.github_project.repo = value;
+        break;
+      case 'project_number':
+        settings.github_project.project_number = value === 'null' ? null : parseInt(value, 10);
+        break;
+      case 'owner':
+        settings.github_project.owner = value;
+        break;
+    }
+  }
+
+  writeSettings(cwd, settings);
+  output({ written: true, settings }, raw);
+}
+
+// ─── Sync Agent Teams ───────────────────────────────────────────────────────
+
+function cmdSyncAgentTeams(cwd, raw) {
+  // Source of truth: runtime settings.json env var (e.g. .claude/settings.json)
+  const claudeSettingsPath = path.join(cwd, RUNTIME_CONFIG_DIR, 'settings.json');
+  let claudeEnabled = false;
+  try {
+    const claudeRaw = fs.readFileSync(claudeSettingsPath, 'utf-8');
+    const claudeSettings = JSON.parse(claudeRaw);
+    const val = claudeSettings?.env?.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    claudeEnabled = val === '1' || val === 'true';
+  } catch {
+    // File doesn't exist or is invalid — treat as disabled
+  }
+
+  // Sync ACE settings to match Claude's source of truth
+  const settings = loadSettings(cwd);
+  const wasDifferent = settings.agent_teams !== claudeEnabled;
+  if (wasDifferent) {
+    settings.agent_teams = claudeEnabled;
+    writeSettings(cwd, settings);
+  }
+
+  output({ agent_teams: claudeEnabled, synced: wasDifferent }, raw);
+}
+
+// ─── Write Agent Teams Setting ──────────────────────────────────────────────
+
+function cmdWriteAgentTeamsSetting(cwd, raw, extraArgs) {
+  const enabled = extraArgs[0] === 'true';
+  const settings = loadSettings(cwd);
+  settings.agent_teams = enabled;
+  writeSettings(cwd, settings);
+
+  // Also update the project's runtime settings.json (e.g. .claude/)
+  const claudeDir = path.join(cwd, RUNTIME_CONFIG_DIR);
+  const claudeSettingsPath = path.join(claudeDir, 'settings.json');
+
+  let claudeSettings = {};
+  try {
+    const existing = fs.readFileSync(claudeSettingsPath, 'utf-8');
+    claudeSettings = JSON.parse(existing);
+  } catch {
+    // File doesn't exist or is invalid — start fresh
+  }
+
+  if (!claudeSettings.env) {
+    claudeSettings.env = {};
+  }
+
+  if (enabled) {
+    claudeSettings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
+  } else {
+    delete claudeSettings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    // Clean up empty env object
+    if (Object.keys(claudeSettings.env).length === 0) {
+      delete claudeSettings.env;
+    }
+  }
+
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+  }
+  fs.writeFileSync(claudeSettingsPath, JSON.stringify(claudeSettings, null, 2) + '\n', 'utf-8');
+
+  output({ written: true, agent_teams: enabled, settings, claude_settings: claudeSettings }, raw);
+}

package/skills/help/script.test.js

@@ -0,0 +1,183 @@
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert');
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SCRIPT = path.join(__dirname, 'script.js');
+
+/**
+ * Create a minimal ACE project structure in a temp directory.
+ */
+function createTestProject() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
+
+  // .ace/config.json
+  const aceDir = path.join(tmpDir, '.ace');
+  fs.mkdirSync(aceDir, { recursive: true });
+  fs.writeFileSync(path.join(aceDir, 'config.json'), JSON.stringify({
+    version: '0.1.0',
+    projectName: 'test-project',
+    model_profile: 'quality',
+    commit_docs: true,
+    github: { enabled: false },
+  }, null, 2));
+
+  // .ace/settings.json
+  fs.writeFileSync(path.join(aceDir, 'settings.json'), JSON.stringify({
+    model_profile: 'quality',
+    commit_docs: true,
+    agent_teams: false,
+    github_project: { enabled: false, gh_installed: false, repo: '', project_number: null, owner: '' },
+  }, null, 2));
+
+  return tmpDir;
+}
+
+function runScript(subcommand, args, cwd) {
+  return execSync(`node "${SCRIPT}" ${subcommand} ${args}`, {
+    cwd,
+    encoding: 'utf-8',
+    timeout: 10000,
+  });
+}
+
+function cleanup(tmpDir) {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('help script', () => {
+
+  describe('init', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns valid JSON with environment detection', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+
+      assert.strictEqual(typeof result.commit_docs, 'boolean');
+      assert.strictEqual(typeof result.has_git, 'boolean');
+      assert.strictEqual(typeof result.has_product_vision, 'boolean');
+      assert.strictEqual(typeof result.has_system_architecture, 'boolean');
+      assert.strictEqual(typeof result.has_system_structure, 'boolean');
+      assert.strictEqual(typeof result.has_coding_standards, 'boolean');
+      assert.strictEqual(typeof result.has_testing_framework, 'boolean');
+      assert.strictEqual(typeof result.is_brownfield, 'boolean');
+      assert.strictEqual(typeof result.is_greenfield, 'boolean');
+      assert.ok(result.product_owner_model, 'should have product_owner_model');
+    });
+
+    it('detects brownfield vs greenfield correctly', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+      assert.strictEqual(result.is_brownfield, !result.is_greenfield);
+    });
+  });
+
+  describe('ensure-settings', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('reports settings already exist when they do', () => {
+      const result = JSON.parse(runScript('ensure-settings', '', tmpDir));
+      assert.strictEqual(result.created, false);
+      assert.ok(result.settings);
+    });
+
+    it('creates settings when they do not exist', () => {
+      const freshDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
+      const aceDir = path.join(freshDir, '.ace');
+      fs.mkdirSync(aceDir, { recursive: true });
+      fs.writeFileSync(path.join(aceDir, 'config.json'), JSON.stringify({
+        version: '0.1.0',
+        projectName: 'test',
+        model_profile: 'balanced',
+        commit_docs: true,
+        github: { enabled: false },
+      }, null, 2));
+
+      const result = JSON.parse(runScript('ensure-settings', '', freshDir));
+      assert.strictEqual(result.created, true);
+      assert.ok(result.settings);
+      assert.strictEqual(result.settings.model_profile, 'balanced');
+
+      cleanup(freshDir);
+    });
+  });
+
+  describe('sync-agent-teams', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns agent_teams boolean', () => {
+      const result = JSON.parse(runScript('sync-agent-teams', '', tmpDir));
+      assert.strictEqual(typeof result.agent_teams, 'boolean');
+      assert.strictEqual(typeof result.synced, 'boolean');
+    });
+  });
+
+  describe('write-agent-teams', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('enables agent teams', () => {
+      const result = JSON.parse(runScript('write-agent-teams', 'true', tmpDir));
+      assert.strictEqual(result.written, true);
+      assert.strictEqual(result.agent_teams, true);
+
+      // Verify .ace/settings.json updated
+      const settings = JSON.parse(fs.readFileSync(path.join(tmpDir, '.ace', 'settings.json'), 'utf-8'));
+      assert.strictEqual(settings.agent_teams, true);
+    });
+
+    it('disables agent teams', () => {
+      const result = JSON.parse(runScript('write-agent-teams', 'false', tmpDir));
+      assert.strictEqual(result.written, true);
+      assert.strictEqual(result.agent_teams, false);
+
+      const settings = JSON.parse(fs.readFileSync(path.join(tmpDir, '.ace', 'settings.json'), 'utf-8'));
+      assert.strictEqual(settings.agent_teams, false);
+    });
+  });
+
+  describe('verify-path-exists', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns true for existing path', () => {
+      const result = runScript('verify-path-exists', '.ace/config.json --raw', tmpDir).trim();
+      assert.strictEqual(result, 'true');
+    });
+
+    it('returns false for non-existing path', () => {
+      const result = runScript('verify-path-exists', 'nonexistent/file.md --raw', tmpDir).trim();
+      assert.strictEqual(result, 'false');
+    });
+  });
+
+  describe('error handling', () => {
+    it('errors on unknown command', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+
+    it('errors on verify-path-exists without path', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" verify-path-exists`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+  });
+});