guild-agents 1.4.0 → 2.0.0

package/src/commands/stats.js

@@ -1,147 +0,0 @@
-/**
- * stats.js — Token usage stats command.
- */
-
-import * as p from '@clack/prompts';
-import chalk from 'chalk';
-import { existsSync, unlinkSync, copyFileSync } from 'fs';
-import { join } from 'path';
-import { loadUsage, aggregate, estimateWithProfile } from '../utils/accounting.js';
-import { getModelShortName } from '../utils/pricing.js';
-
-const USAGE_PATH = join('.claude', 'guild', 'usage.json');
-
-function fmt(n) {
-  return n.toLocaleString('en-US');
-}
-
-function usd(n) {
-  return `$${n.toFixed(2)}`;
-}
-
-function pct(part, total) {
-  if (total === 0) return '0%';
-  return `${Math.round((part / total) * 100)}%`;
-}
-
-const PERIOD_LABELS = {
-  today: 'Today',
-  week: 'Last 7 days',
-  month: 'Last 30 days',
-  all: 'All time',
-};
-
-export function formatCsv(entries) {
-  const headers = 'timestamp,workflow,agent,tier,model,inputTokens,outputTokens,totalTokens,estimatedCostUSD';
-  const rows = entries.map(e =>
-    `${e.timestamp},${e.workflow},${e.agent},${e.tier},${e.model},${e.inputTokens},${e.outputTokens},${e.totalTokens},${e.estimatedCostUSD.toFixed(6)}`
-  );
-  return [headers, ...rows].join('\n') + '\n';
-}
-
-export async function runStats(options = {}) {
-  const root = process.cwd();
-
-  if (options.reset) {
-    return handleReset(root, options.force);
-  }
-
-  if (options.export === 'csv') {
-    const usage = loadUsage(root);
-    if (usage.entries.length === 0) {
-      console.log('No usage data to export.');
-      return;
-    }
-    process.stdout.write(formatCsv(usage.entries));
-    return;
-  }
-
-  const period = options.period || 'month';
-  const totals = aggregate(root, period);
-
-  p.intro(chalk.bold.cyan(`Guild Usage Stats — ${PERIOD_LABELS[period] || period}`));
-
-  if (totals.totalTokens === 0) {
-    p.log.info('No usage data yet. Token tracking will begin when workflows record usage.');
-    p.outro('');
-    return;
-  }
-
-  p.log.step('Summary');
-  p.log.info(`  Workflows executed:  ${chalk.bold(fmt(totals.workflowCount))}`);
-  p.log.info(`  Total tokens:        ${chalk.bold(fmt(totals.totalTokens))}`);
-  p.log.info(`  Estimated cost:      ${chalk.bold.green(usd(totals.totalCostUSD))}`);
-
-  if (Object.keys(totals.tokensByTier).length > 0) {
-    p.log.step('By tier');
-    for (const [tier, tokens] of Object.entries(totals.tokensByTier)) {
-      p.log.info(`  ${tier.padEnd(12)} ${fmt(tokens).padStart(10)} tok  (${pct(tokens, totals.totalTokens).padStart(4)})`);
-    }
-  }
-
-  if (Object.keys(totals.tokensByModel).length > 0) {
-    p.log.step('By model');
-    for (const [model, tokens] of Object.entries(totals.tokensByModel)) {
-      p.log.info(`  ${getModelShortName(model).padEnd(12)} ${fmt(tokens).padStart(10)} tok`);
-    }
-  }
-
-  if (Object.keys(totals.tokensByWorkflow).length > 0) {
-    p.log.step('Top workflows');
-    const sorted = Object.entries(totals.tokensByWorkflow).sort((a, b) => b[1] - a[1]);
-    for (const [wf, tokens] of sorted) {
-      p.log.info(`  ${wf.padEnd(20)} ${fmt(tokens).padStart(10)} tok`);
-    }
-  }
-
-  if (options.compare) {
-    const usage = loadUsage(root);
-    const filtered = usage.entries;
-    const maxCost = estimateWithProfile(filtered, 'max');
-    const proCost = estimateWithProfile(filtered, 'pro');
-    const allOpusCost = estimateWithProfile(filtered, 'all-opus');
-
-    p.log.step('Profile comparison');
-    p.log.info(`  ${'max'.padEnd(12)} ${usd(maxCost).padStart(10)}    —`);
-    p.log.info(`  ${'pro'.padEnd(12)} ${usd(proCost).padStart(10)}    ${diffLabel(proCost, maxCost)}`);
-    p.log.info(`  ${'all-opus'.padEnd(12)} ${usd(allOpusCost).padStart(10)}    ${diffLabel(allOpusCost, maxCost)}`);
-  }
-
-  p.outro('');
-}
-
-function diffLabel(cost, baseline) {
-  if (baseline === 0) return '';
-  const diff = ((cost - baseline) / baseline) * 100;
-  const sign = diff >= 0 ? '+' : '';
-  return chalk.gray(`${sign}${Math.round(diff)}%`);
-}
-
-async function handleReset(root, force) {
-  const filePath = join(root, USAGE_PATH);
-
-  p.intro(chalk.bold.cyan('Guild — Reset Usage Stats'));
-
-  if (!existsSync(filePath)) {
-    p.log.info('No usage data found. Nothing to reset.');
-    p.outro('');
-    return;
-  }
-
-  if (!force) {
-    const confirmed = await p.confirm({
-      message: 'This will delete all usage history. Continue?',
-      initialValue: false,
-    });
-
-    if (p.isCancel(confirmed) || !confirmed) {
-      p.cancel('Reset cancelled.');
-      return;
-    }
-  }
-
-  copyFileSync(filePath, filePath + '.bak');
-  unlinkSync(filePath);
-  p.log.success(`${chalk.green('✓')} Usage history deleted. Backup saved as usage.json.bak.`);
-  p.outro('');
-}

package/src/templates/agents/db-migration.md

@@ -1,51 +0,0 @@
----
-name: db-migration
-description: "Schema changes and safe migrations"
-tools: Read, Write, Edit, Bash, Glob, Grep
-permissionMode: bypassPermissions
-default-tier: execution
----
-
-# DB Migration
-
-You are the database specialist for [PROJECT]. Your job is to design and execute schema changes safely, ensuring existing data integrity and production performance.
-
-## Responsibilities
-
-- Design schema changes with up and down migrations
-- Verify impact on existing data before migrating
-- Consider production performance (large tables, locks, indexes)
-- Use the project's ORM and migration tools
-- Ensure every migration is reversible
-
-## What you do NOT do
-
-- You do not implement application logic -- that is the Developer's role
-- You do not define system architecture -- that is the Tech Lead's role
-- You do not validate functional behavior -- that is QA's role
-- You do not prioritize tasks -- that is the Product Owner's role
-
-## Process
-
-1. Read CLAUDE.md and SESSION.md to understand the project's migration tools
-2. Analyze the required schema change and its impact on existing data
-3. Design the migration: up (apply) and down (revert)
-4. Verify the migration is safe for production data
-5. Implement using the project's ORM tools
-6. Document performance considerations if applicable
-
-## Quality criteria
-
-- Every migration has functional up and down operations
-- Impact on existing data is verified (no data loss)
-- Locks and performance on large tables are considered
-- Indexes are created/modified concurrently when possible
-- Default values are handled correctly for existing rows
-
-## Behavior rules
-
-- Always read CLAUDE.md and SESSION.md before designing migrations
-- Never make destructive changes without a prior data migration
-- If the change affects tables with many records, warn about performance
-- Prefer small, incremental migrations over massive changes
-- Verify compatibility with the project's ORM and tools

package/src/templates/agents/learnings-extractor.md

@@ -1,49 +0,0 @@
----
-name: learnings-extractor
-description: "Extracts compound learnings from pipeline executions"
-tools: Read, Glob, Grep
-permissionMode: plan
-default-tier: routine
----
-
-# Learnings Extractor
-
-You are the Learnings Extractor for [PROJECT]. Your job is to analyze completed pipeline traces and extract reusable patterns, recurring issues, and optimization opportunities that improve future executions.
-
-## Responsibilities
-
-- Read pipeline trace files from `.claude/guild/traces/`
-- Identify patterns across multiple executions (recurring review loops, common failures)
-- Extract actionable learnings that reduce future iteration count
-- Update `.claude/guild/learnings.md` with new findings
-- Prioritize learnings by impact (reduces tokens, reduces loops, improves quality)
-
-## What you do NOT do
-
-- You do not implement features — that is the Developer's role
-- You do not evaluate strategy — that is the Advisor's role
-- You do not modify source code — you only read traces and write learnings
-
-## Process
-
-1. Read the pipeline trace provided as input
-2. Analyze step results, loop counts, and failure patterns
-3. Compare with existing learnings in `.claude/guild/learnings.md`
-4. Extract new learnings or reinforce existing ones
-5. Write updated learnings in a structured format
-
-## Output format
-
-Each learning should include:
-
-- **Pattern**: What was observed
-- **Frequency**: How often it occurs (first-seen or recurring)
-- **Recommendation**: What to do differently next time
-- **Impact**: Expected reduction in loops, tokens, or failures
-
-## Behavior rules
-
-- Never duplicate an existing learning — update its frequency instead
-- Focus on actionable recommendations, not observations
-- Keep learnings concise — one paragraph maximum per entry
-- Tag learnings with the workflow they came from

package/src/templates/agents/platform-expert.md

@@ -1,92 +0,0 @@
----
-name: platform-expert
-description: "Diagnoses and resolves Claude Code integration issues -- permissions, subagents, hooks, settings"
-tools: Read, Write, Edit, Bash, Glob, Grep
-permissionMode: bypassPermissions
-default-tier: execution
----
-
-# Platform Expert
-
-You are the Platform Expert for [PROJECT]. Your job is to diagnose and resolve integration issues between Guild and Claude Code, including tool permissions, subagent configuration, hooks, and settings.
-
-## Responsibilities
-
-- Diagnose permission issues in subagents (Bash denied, tool access, etc.)
-- Configure agent frontmatter for correct tool access
-- Implement PreToolUse hooks for permission workarounds
-- Maintain compatibility with Claude Code versions
-- Document platform limitations and known workarounds
-
-## Specialized knowledge
-
-### Subagent Permission Model
-
-Claude Code subagents run in `dontAsk` mode by default. They do not inherit permissions from `settings.json`. To grant Bash access:
-
-1. **Frontmatter `tools` field:** Explicitly declare available tools
-2. **Frontmatter `permissionMode`:** Controls permission level
-3. **PreToolUse hooks:** Workaround to auto-approve tools
-
-### Agent configuration with Bash
-
-```yaml
----
-name: agent-name
-description: "Description for delegation"
-tools: Read, Write, Edit, Bash, Glob, Grep
-permissionMode: bypassPermissions
----
-```
-
-### Agent configuration without Bash (analysis)
-
-```yaml
----
-name: agent-name
-description: "Description for delegation"
-tools: Read, Glob, Grep
-permissionMode: plan
----
-```
-
-### PreToolUse Hook workaround
-
-If `permissionMode` does not work, use hooks:
-
-```yaml
-hooks:
-  PreToolUse:
-    - matcher: "Bash"
-      hooks:
-        - type: command
-          command: "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\"}}'"
-```
-
-### Known Claude Code bugs
-
-- Issue #18950: Subagents do not inherit permissions from settings.json (OPEN)
-- Issue #14714: Subagents do not inherit tools from parent
-- Issue #21585: subagent_type "Bash" fabricates output instead of executing
-
-## What you do NOT do
-
-- You do not implement business features -- that is the Developer's role
-- You do not define application architecture -- that is the Tech Lead's role
-- You do not evaluate strategy -- that is the Advisor's role
-
-## Process
-
-1. Read CLAUDE.md to understand the current configuration
-2. Identify the permission/integration problem
-3. Research Claude Code documentation and known issues
-4. Propose a solution using frontmatter, hooks, or settings
-5. Test the solution with a test subagent
-6. Document the solution and workaround
-
-## Behavior rules
-
-- Always verify the Claude Code version before diagnosing
-- Prioritize official solutions over workarounds
-- Document ALL workarounds with a reference to the GitHub issue
-- Do not assume a platform fix works -- always test it

package/src/templates/agents/product-owner.md

@@ -1,52 +0,0 @@
----
-name: product-owner
-description: "Converts approved ideas into concrete, implementable tasks"
-tools: Read, Glob, Grep
-permissionMode: plan
-default-tier: reasoning
----
-
-# Product Owner
-
-You are the Product Owner for [PROJECT]. Your job is to translate ideas approved by the Advisor into concrete tasks with verifiable acceptance criteria that the team can implement without ambiguity.
-
-## Responsibilities
-
-- Convert approved ideas into implementable tasks with clear acceptance criteria
-- Break down large features into atomic, independent tasks
-- Prioritize the backlog by business value and impact
-- Define the "done" for each task in a verifiable way
-- Maintain traceability between the project vision and individual tasks
-
-## What you do NOT do
-
-- You do not define architecture or technical patterns -- that is the Tech Lead's role
-- You do not implement code -- that is the Developer's role
-- You do not evaluate domain coherence -- that is the Advisor's role
-- You do not validate functional behavior -- that is QA's role
-
-## Process
-
-1. Read CLAUDE.md and SESSION.md to understand the current state
-2. Receive the idea or feature approved by the Advisor
-3. Break it down into concrete tasks with defined scope
-4. Define verifiable acceptance criteria for each task
-5. Estimate relative effort and suggest implementation order
-
-## Output format
-
-For each task:
-
-- **Title**: Concrete action in imperative form
-- **Description**: What is needed and why (2-3 sentences)
-- **Acceptance criteria**: Verifiable list (checkboxes)
-- **Technical tasks**: Breakdown of implementation steps
-- **Estimate**: Small / Medium / Large
-
-## Behavior rules
-
-- Always read CLAUDE.md and SESSION.md before planning
-- Each acceptance criterion must be verifiable with yes/no
-- If a task is too large to implement in a single session, split it
-- Do not assume technical context -- leave implementation details to the Tech Lead
-- Prioritize delivered value over technical perfection

package/src/templates/skills/dev-flow/SKILL.md

@@ -1,83 +0,0 @@
----
-name: dev-flow
-description: "Shows current pipeline phase and what comes next"
-user-invocable: true
-workflow:
-  version: 1
-  steps:
-    - id: read-state
-      role: system
-      intent: "Read SESSION.md to determine current feature and pipeline phase."
-      commands: [cat SESSION.md]
-      produces: [session-state, feature-name, current-phase]
-    - id: present-flow
-      role: system
-      intent: "Display pipeline progress with phase checklist and suggest next step."
-      requires: [session-state, feature-name, current-phase]
-      produces: [flow-display]
-      gate: true
----
-
-# Dev Flow
-
-Shows the current phase of the development pipeline and suggests the next step. Useful for resuming work when you do not remember where you left off in the flow.
-
-## When to use
-
-- When resuming work and you do not remember the current phase
-- To see the progress of the build-feature pipeline
-- To decide which skill to run next
-
-## Usage
-
-`/dev-flow`
-
-## Process
-
-### Step 1 — Read state
-
-Read `SESSION.md` to determine:
-
-- Whether there is a feature in progress
-- Which pipeline phase it is in
-- What has been completed and what remains
-
-### Step 2 — Determine current phase
-
-The pipeline phases are:
-
-1. **Evaluation** (Advisor) — go/no-go
-2. **Specification** (Product Owner) — acceptance criteria
-3. **Technical Approach** (Tech Lead) — implementation plan
-4. **Implementation** (Developer) — code and tests
-5. **Review** (Code Reviewer) — quality review
-6. **QA** — functional validation
-
-### Step 3 — Present flow state
-
-```text
-Dev Flow — [feature name]
-
-[x] Phase 1 — Evaluation (completed)
-[x] Phase 2 — Specification (completed)
-[ ] Phase 3 — Technical Approach (pending) <-- you are here
-[ ] Phase 4 — Implementation
-[ ] Phase 5 — Review
-[ ] Phase 6 — QA
-
-Next step: Run /build-feature to continue from Phase 3.
-```
-
-If there is no feature in progress, report that there is no active pipeline and suggest `/new-feature` or `/build-feature`.
-
-## Example Session
-
-```text
-User: /dev-flow
-
-Current pipeline: build-feature "add user preferences"
-Phase: 4 of 6 — Implementation
-Developer agent active.
-
-Next: Phase 5 — Code Review
-```

package/src/templates/skills/dev-flow/evals/evals.json

@@ -1,36 +0,0 @@
-{
-  "skill": "dev-flow",
-  "evals": [
-    {
-      "id": "df-has-steps",
-      "description": "Dev flow has read-state and present-flow steps",
-      "expectations": [
-        { "text": "Has read-state step", "assertion": "step-exists:read-state" },
-        { "text": "Has present-flow step", "assertion": "step-exists:present-flow" }
-      ]
-    },
-    {
-      "id": "df-all-system",
-      "description": "All steps are system role",
-      "expectations": [
-        { "text": "read-state is system", "assertion": "step-role:read-state:system" },
-        { "text": "present-flow is system", "assertion": "step-role:present-flow:system" }
-      ]
-    },
-    {
-      "id": "df-presentation-gate",
-      "description": "Present-flow step has a gate for user confirmation",
-      "expectations": [
-        { "text": "present-flow has gate", "assertion": "gate-exists:present-flow" }
-      ]
-    },
-    {
-      "id": "df-dependencies",
-      "description": "Present-flow requires session state",
-      "expectations": [
-        { "text": "present-flow requires session-state", "assertion": "step-requires:present-flow:session-state" },
-        { "text": "present-flow requires current-phase", "assertion": "step-requires:present-flow:current-phase" }
-      ]
-    }
-  ]
-}

package/src/templates/skills/dev-flow/evals/triggers.json

@@ -1,16 +0,0 @@
-{
-  "skill": "dev-flow",
-  "matcherType": "keyword",
-  "description": "Shows current pipeline phase and what comes next",
-  "threshold": 0.3,
-  "tests": [
-    { "prompt": "what phase am I in", "shouldTrigger": true },
-    { "prompt": "show the current pipeline phase", "shouldTrigger": true },
-    { "prompt": "what comes next in the flow", "shouldTrigger": true },
-    { "prompt": "where did I leave off", "shouldTrigger": true, "keywordExpected": false },
-    { "prompt": "create a pull request", "shouldTrigger": false },
-    { "prompt": "review my code", "shouldTrigger": false },
-    { "prompt": "fix this bug", "shouldTrigger": false },
-    { "prompt": "run the tests", "shouldTrigger": false }
-  ]
-}

package/src/templates/skills/new-feature/SKILL.md

@@ -1,119 +0,0 @@
----
-name: new-feature
-description: "Creates branch and scaffold for a new feature"
-user-invocable: true
-workflow:
-  version: 1
-  steps:
-    - id: get-name
-      role: system
-      intent: "Obtain feature name from user input or prompt for it."
-      produces: [feature-name, feature-description]
-      gate: true
-    - id: create-branch
-      role: system
-      intent: "Create feature branch (simple checkout or worktree for parallel execution)."
-      commands: [git checkout -b]
-      requires: [feature-name]
-      produces: [branch-name]
-    - id: update-session
-      role: system
-      intent: "Update SESSION.md with new feature context, date, and state."
-      requires: [feature-name, feature-description, branch-name]
-      produces: [session-update]
-      gate: true
-    - id: create-issue
-      role: system
-      intent: "Optionally create GitHub Issue for the feature via gh CLI."
-      commands: [gh issue create]
-      requires: [feature-name, feature-description]
-      produces: [issue-url]
-      condition: user-wants-issue
-    - id: confirm
-      role: system
-      intent: "Confirm branch created, SESSION.md updated, issue created. Suggest /build-feature."
-      requires: [branch-name, session-update]
-      produces: [confirmation]
-      gate: true
----
-
-# New Feature
-
-Prepares the environment for working on a new feature: creates a branch, updates SESSION.md, and optionally creates a GitHub Issue.
-
-## When to use
-
-- When starting a new feature before writing code
-- When you want to record the feature context in SESSION.md
-
-## Usage
-
-`/new-feature [feature-name]`
-
-## Process
-
-### Step 1 — Get name
-
-If the user did not provide a name, ask for:
-
-- Short name for the feature (will be used in the branch name)
-- Brief description (1-2 sentences)
-
-### Step 2 — Create branch with worktree isolation
-
-When running in parallel with other agents, use git worktrees for isolation. When running standalone, a simple branch is sufficient.
-
-**For parallel execution (multiple build-features at once):**
-
-```bash
-git worktree add .claude/worktrees/feature-[name] -b feature/[feature-name] develop
-```
-
-All subsequent operations should use `.claude/worktrees/feature-[name]` as the working directory.
-
-**For standalone execution:**
-
-```bash
-git checkout -b feature/[feature-name]
-```
-
-If the branch already exists, ask whether to switch to it or create a new one.
-
-**Cleanup:** At skill exit, if using worktrees, the caller is responsible for cleanup via `git worktree remove .claude/worktrees/feature-[name]` after the PR is merged.
-
-### Step 3 — Update SESSION.md
-
-Update SESSION.md with the new feature context:
-
-- **Date:** current date
-- **Task in progress:** feature name
-- **State:** Feature started — pending implementation
-
-## Example Session
-
-```text
-User: /new-feature user-preferences
-
-Branch created: feature/user-preferences
-SESSION.md updated with feature context.
-GitHub Issue #42 created.
-
-Next: Run /build-feature to implement.
-```
-
-### Step 4 — GitHub Issue (optional)
-
-If the project has GitHub integration configured in PROJECT.md:
-
-1. Ask whether to create a GitHub Issue for the feature
-2. If accepted, create the issue with `gh issue create`
-3. Record the issue URL in SESSION.md
-
-### Step 5 — Confirm
-
-Confirm to the user:
-
-- Branch created: `feature/[name]`
-- SESSION.md updated
-- GitHub Issue created (if applicable)
-- Suggest: "Run /build-feature to implement the full feature"

package/src/templates/skills/new-feature/evals/evals.json

@@ -1,41 +0,0 @@
-{
-  "skill": "new-feature",
-  "evals": [
-    {
-      "id": "nf-has-core-steps",
-      "description": "New feature has name, branch, session, confirm steps",
-      "expectations": [
-        { "text": "Has get-name step", "assertion": "step-exists:get-name" },
-        { "text": "Has create-branch step", "assertion": "step-exists:create-branch" },
-        { "text": "Has update-session step", "assertion": "step-exists:update-session" },
-        { "text": "Has confirm step", "assertion": "step-exists:confirm" }
-      ]
-    },
-    {
-      "id": "nf-optional-issue",
-      "description": "GitHub issue creation step exists",
-      "expectations": [
-        { "text": "Has create-issue step", "assertion": "step-exists:create-issue" }
-      ]
-    },
-    {
-      "id": "nf-gates",
-      "description": "Gates at name input, session update, and confirmation",
-      "expectations": [
-        { "text": "get-name has gate", "assertion": "gate-exists:get-name" },
-        { "text": "update-session has gate", "assertion": "gate-exists:update-session" },
-        { "text": "confirm has gate", "assertion": "gate-exists:confirm" }
-      ]
-    },
-    {
-      "id": "nf-all-system",
-      "description": "All steps are system role",
-      "expectations": [
-        { "text": "get-name is system", "assertion": "step-role:get-name:system" },
-        { "text": "create-branch is system", "assertion": "step-role:create-branch:system" },
-        { "text": "update-session is system", "assertion": "step-role:update-session:system" },
-        { "text": "confirm is system", "assertion": "step-role:confirm:system" }
-      ]
-    }
-  ]
-}