@bantay/cli 0.2.0 → 0.3.1

package/src/export/claude.ts

@@ -4,7 +4,7 @@
 
 import { readFile, writeFile, access } from "fs/promises";
 import { join } from "path";
-import { read as readAide } from "../aide";
+import { read as readAide, resolveAidePath } from "../aide";
 import {
   extractConstraints,
   extractFoundations,
@@ -27,7 +27,8 @@ import {
 export function generateClaudeSection(
   constraints: ExtractedConstraint[],
   foundations: ExtractedFoundation[],
-  invariants: ExtractedInvariant[]
+  invariants: ExtractedInvariant[],
+  aideFilename: string = "*.aide"
 ): string {
   const lines: string[] = [];
 
@@ -35,7 +36,7 @@ export function generateClaudeSection(
   lines.push("");
   lines.push("## Bantay Project Rules");
   lines.push("");
-  lines.push("*Auto-generated from bantay.aide. Do not edit manually.*");
+  lines.push(`*Auto-generated from ${aideFilename}. Do not edit manually.*`);
   lines.push("");
 
   // Foundations as principles
@@ -184,7 +185,9 @@ export async function exportClaude(
   projectPath: string,
   options: ExportOptions = {}
 ): Promise<ExportResult> {
-  const aidePath = options.aidePath || join(projectPath, "bantay.aide");
+  // Discover aide file if not explicitly provided
+  const resolved = await resolveAidePath(projectPath, options.aidePath);
+  const aidePath = resolved.path;
   const outputPath = options.outputPath || join(projectPath, "CLAUDE.md");
 
   // Read the aide tree
@@ -196,7 +199,7 @@ export async function exportClaude(
   const invariants = extractInvariants(tree);
 
   // Generate section content
-  const section = generateClaudeSection(constraints, foundations, invariants);
+  const section = generateClaudeSection(constraints, foundations, invariants, resolved.filename);
 
   // Read existing file if it exists
   let existingContent = "";

package/src/export/codex.ts

@@ -5,7 +5,7 @@
 
 import { readFile, writeFile, access } from "fs/promises";
 import { join } from "path";
-import { read as readAide } from "../aide";
+import { read as readAide, resolveAidePath } from "../aide";
 import {
   extractConstraints,
   extractFoundations,
@@ -33,7 +33,9 @@ export async function exportCodex(
   projectPath: string,
   options: ExportOptions = {}
 ): Promise<ExportResult> {
-  const aidePath = options.aidePath || join(projectPath, "bantay.aide");
+  // Discover aide file if not explicitly provided
+  const resolved = await resolveAidePath(projectPath, options.aidePath);
+  const aidePath = resolved.path;
   const outputPath = options.outputPath || join(projectPath, "AGENTS.md");
 
   // Read the aide tree
@@ -45,7 +47,7 @@ export async function exportCodex(
   const invariants = extractInvariants(tree);
 
   // Generate section content (same format as claude)
-  const section = generateClaudeSection(constraints, foundations, invariants);
+  const section = generateClaudeSection(constraints, foundations, invariants, resolved.filename);
 
   // Read existing file if it exists
   let existingContent = "";

package/src/export/cursor.ts

@@ -4,7 +4,7 @@
 
 import { readFile, writeFile, access } from "fs/promises";
 import { join } from "path";
-import { read as readAide } from "../aide";
+import { read as readAide, resolveAidePath } from "../aide";
 import {
   extractConstraints,
   extractFoundations,
@@ -32,7 +32,9 @@ export async function exportCursor(
   projectPath: string,
   options: ExportOptions = {}
 ): Promise<ExportResult> {
-  const aidePath = options.aidePath || join(projectPath, "bantay.aide");
+  // Discover aide file if not explicitly provided
+  const resolved = await resolveAidePath(projectPath, options.aidePath);
+  const aidePath = resolved.path;
   const outputPath = options.outputPath || join(projectPath, ".cursorrules");
 
   // Read the aide tree
@@ -44,7 +46,7 @@ export async function exportCursor(
   const invariants = extractInvariants(tree);
 
   // Generate section content (same format as claude)
-  const section = generateClaudeSection(constraints, foundations, invariants);
+  const section = generateClaudeSection(constraints, foundations, invariants, resolved.filename);
 
   // Read existing file if it exists
   let existingContent = "";

package/src/export/invariants.ts

@@ -4,19 +4,19 @@
 
 import { readFile, writeFile } from "fs/promises";
 import { join } from "path";
-import { read as readAide } from "../aide";
+import { read as readAide, resolveAidePath } from "../aide";
 import { extractInvariants, groupBy } from "./aide-reader";
 import type { ExportOptions, ExportResult, ExtractedInvariant } from "./types";
 
 /**
  * Generate invariants.md content from the aide tree
  */
-export function generateInvariantsMd(invariants: ExtractedInvariant[]): string {
+export function generateInvariantsMd(invariants: ExtractedInvariant[], aideFilename: string = "*.aide"): string {
   const lines: string[] = [];
 
   lines.push("# Invariants");
   lines.push("");
-  lines.push("Rules this project must never break. Generated from bantay.aide.");
+  lines.push(`Rules this project must never break. Generated from ${aideFilename}.`);
   lines.push("");
 
   // Group by category
@@ -66,7 +66,9 @@ export async function exportInvariants(
   projectPath: string,
   options: ExportOptions = {}
 ): Promise<ExportResult> {
-  const aidePath = options.aidePath || join(projectPath, "bantay.aide");
+  // Discover aide file if not explicitly provided
+  const resolved = await resolveAidePath(projectPath, options.aidePath);
+  const aidePath = resolved.path;
   const outputPath = options.outputPath || join(projectPath, "invariants.md");
 
   // Read the aide tree
@@ -76,7 +78,7 @@ export async function exportInvariants(
   const invariants = extractInvariants(tree);
 
   // Generate content
-  const content = generateInvariantsMd(invariants);
+  const content = generateInvariantsMd(invariants, resolved.filename);
 
   // Write unless dry run
   if (!options.dryRun) {

package/src/generators/claude-commands.ts

@@ -0,0 +1,61 @@
+/**
+ * Generators for Claude Code slash command files
+ *
+ * These files are placed in .claude/commands/ and appear as
+ * slash commands in Claude Code (e.g., /bantay-interview)
+ *
+ * Prompts are stored as markdown files in src/templates/commands/
+ * for readability and easy editing.
+ */
+
+import { readFileSync } from "fs";
+import { join } from "path";
+
+/**
+ * Generate the bantay-interview.md command
+ *
+ * This command guides Claude through an interactive session to
+ * build out the project's aide structure through conversation.
+ */
+export function generateInterviewCommand(): string {
+  return readFileSync(
+    join(__dirname, "../templates/commands/bantay-interview.md"),
+    "utf-8"
+  );
+}
+
+/**
+ * Generate the bantay-status.md command
+ *
+ * This command runs bantay status and discusses the results.
+ */
+export function generateStatusCommand(): string {
+  return readFileSync(
+    join(__dirname, "../templates/commands/bantay-status.md"),
+    "utf-8"
+  );
+}
+
+/**
+ * Generate the bantay-check.md command
+ *
+ * This command runs bantay check and helps fix any failures.
+ */
+export function generateCheckCommand(): string {
+  return readFileSync(
+    join(__dirname, "../templates/commands/bantay-check.md"),
+    "utf-8"
+  );
+}
+
+/**
+ * Generate the bantay-orchestrate.md command
+ *
+ * This command orchestrates multi-agent builds from the aide task list.
+ */
+export function generateOrchestrateCommand(): string {
+  return readFileSync(
+    join(__dirname, "../templates/commands/bantay-orchestrate.md"),
+    "utf-8"
+  );
+}

package/src/templates/commands/bantay-check.md

@@ -0,0 +1,58 @@
+# Bantay Check
+
+Run `bantay check` to verify all invariants, explain any failures, and propose fixes.
+
+## What to Do
+
+1. Run the check command:
+```bash
+bantay check
+```
+
+2. If all checks pass:
+   - Confirm that all invariants are satisfied
+   - Note the total number of checks run
+
+3. If any checks fail:
+   - Explain each failure clearly
+   - Show the file and line number where the violation occurred
+   - Explain WHY this violates the invariant
+   - Propose a specific fix
+
+## Explaining Failures
+
+For each failed invariant, provide:
+
+1. **The Rule**: What the invariant requires
+2. **The Violation**: What code breaks the rule
+3. **The Risk**: Why this matters (security, data integrity, etc.)
+4. **The Fix**: Specific code changes to resolve it
+
+## Example Response
+
+"Bantay check found 1 failure:
+
+**inv_auth_required** - FAILED
+- File: src/routes/admin.ts:45
+- Violation: Route `/admin/users` has no authentication middleware
+- Risk: Unauthenticated users could access admin functionality
+- Fix: Add the auth middleware:
+
+```typescript
+// Before
+router.get('/admin/users', getUsers);
+
+// After
+router.get('/admin/users', requireAuth, requireAdmin, getUsers);
+```
+
+Would you like me to apply this fix?"
+
+## Diff Mode
+
+For faster checks during development, suggest:
+```bash
+bantay check --diff HEAD
+```
+
+This only checks invariants affected by recent changes.

package/src/templates/commands/bantay-interview.md

@@ -0,0 +1,155 @@
+# Bantay Aide Interview
+
+You are the Bantay aide interviewer. You help the developer maintain
+their project's behavioral specification through conversation.
+
+Read CLAUDE.md and the .aide file before doing anything.
+
+## Determine mode
+
+First, check what exists:
+
+1. `ls *.aide` — does an aide file exist?
+   - **No aide:** Start a new interview (see New Project below)
+   - **Aide exists:** Ask what brings them here today
+
+2. If the aide exists, the developer is here for one of:
+   - **New feature** — behavior that doesn't exist yet
+   - **Bug report** — something isn't working right
+   - **Spec refinement** — tightening an existing scenario or invariant
+
+## New project
+
+If no aide file exists:
+
+1. Ask the developer to describe their product in a few sentences
+2. Ask: who are the primary users and what do they accomplish?
+3. Propose CUJs grouped by area, confirm with the developer
+4. For each CUJ, propose scenarios (given/when/then)
+5. After scenarios, propose invariants — rules that must never break
+6. Ask about constraints (tech stack, hosting, auth strategy)
+7. Ask about foundations (design principles, non-negotiable values)
+8. Ask about wisdom (hard-won lessons, things they've learned the hard way)
+
+Use `bantay aide add`, `bantay aide update`, and `bantay aide link`
+for all mutations. Never hand-edit the YAML.
+
+Run `bantay aide validate` after each section.
+
+## Bug report
+
+When the developer reports a bug:
+
+1. Understand the issue. Ask enough to reproduce it:
+   - What did you expect?
+   - What happened instead?
+   - Where in the app?
+
+2. Check the aide for coverage:
+   ```
+   bantay aide show <likely_cuj_id>
+   ```
+   Look for a scenario that covers this behavior.
+
+3. **If no scenario covers it** — this is an aide gap:
+   - Propose a new scenario with given/when/then
+   - Propose a new invariant if the bug reveals a rule that should never break
+   - Add threat signals to existing invariants if relevant
+   - After the developer confirms:
+     ```
+     bantay aide add sc_... --parent <cuj> --prop "..."
+     bantay aide add inv_... --parent invariants --prop "..."
+     bantay aide link sc_... inv_... --type protected_by
+     bantay aide validate
+     bantay export all
+     bantay aide lock
+     ```
+   - Then: `bantay diff` to show the classified changes
+   - Then: `bantay tasks` to generate the fix list
+   - The reconciliation loop handles the rest
+
+4. **If a scenario already covers it** — this is a code bug:
+   - The aide is correct, the implementation is wrong
+   - Don't touch the aide
+   - Create a GitHub issue:
+     ```
+     gh issue create \
+       --title "Bug: <short description>" \
+       --body "## Scenario
+     <scenario_id>: <scenario name>
+
+     **Given:** <given>
+     **When:** <when>
+     **Expected (from aide):** <then>
+     **Actual:** <what the developer reported>
+
+     ## Linked invariant
+     <invariant_id>: <statement>
+
+     ## Notes
+     The aide correctly specifies this behavior. The implementation
+     does not match. Fix the code to satisfy the scenario."
+     ```
+   - Tell the developer: "The aide already covers this — it's an
+     implementation bug. I've created an issue. Run the fix against
+     the existing scenario."
+
+5. **If partially covered** — the scenario exists but is too loose:
+   - Tighten the scenario (update given/when/then to be more specific)
+   - Add an invariant if the bug reveals a missing constraint
+   - Then follow the aide gap flow: validate → export → lock → diff → tasks
+
+## Feature request
+
+When the developer requests a new feature:
+
+1. Understand the feature:
+   - What should the user be able to do?
+   - Which existing CUJ does this extend, or is it a new CUJ?
+   - Are there new invariants (rules that must hold)?
+
+2. Check the aide:
+   ```
+   bantay aide show <likely_cuj_id>
+   ```
+   Does any existing scenario partially cover this?
+
+3. **New CUJ** — if the feature is a new user journey:
+   - Propose the CUJ with feature description, tier, and area
+   - Propose scenarios with given/when/then
+   - Propose invariants
+   - Wire relationships (protected_by, depends_on)
+   - Validate → export → lock → diff → tasks
+
+4. **Extending existing CUJ** — if adding scenarios to an existing journey:
+   - Propose new scenarios under the existing CUJ
+   - Check if new invariants are needed
+   - Wire relationships
+   - Validate → export → lock → diff → tasks
+
+5. **Cross-cutting** — if the feature touches multiple CUJs:
+   - Propose scenarios under each affected CUJ
+   - Propose shared invariants
+   - Wire depends_on relationships between CUJs if needed
+   - Validate → export → lock → diff → tasks
+
+## Spec refinement
+
+When the developer wants to tighten the spec:
+
+1. Show current state: `bantay aide show <entity_id>`
+2. Discuss what's missing or too loose
+3. Update scenarios, invariants, or constraints
+4. Add threat signals to invariants that lack them
+5. Validate → export → lock → diff → tasks
+
+## Rules
+
+- Always use the CLI for mutations. Never hand-edit YAML.
+- Confirm every addition with the developer before running the command.
+- Run `bantay aide validate` after every batch of changes.
+- The aide is the source of truth. If the aide is correct and the code
+  is wrong, don't change the aide — file an issue.
+- If the aide is missing something, update the aide first, then build.
+- Always end with: validate → export → lock → diff → tasks.
+  That hands off to the reconciliation loop.

package/src/templates/commands/bantay-orchestrate.md

@@ -0,0 +1,164 @@
+You are the team lead for a Bantay-orchestrated build.
+
+Read CLAUDE.md and the .aide file before doing anything.
+
+## Check build state
+
+1. Check if `.bantay/builds/current.md` exists.
+   - **Exists with in_progress:** Resume from where it left off. Read the file, run `bantay status`, check worktrees with `git log`. Respawn any teammates that were mid-work.
+   - **Does not exist:** This is a fresh build or nothing to build. Run `bantay tasks` (diff mode). If no tasks, run `bantay tasks --all`. If still no tasks, report "nothing to build" and stop.
+
+## Constraints
+
+- Maximum 2 teammates at any time
+- You do Phase 0 (foundation) directly — no teammates
+- Every CUJ gets a written plan before a teammate is spawned
+- No teammate is spawned without a validated and committed `.bantay/plans/<cuj_id>.md`
+- Teammates work in separate git worktrees
+- Run `bantay check` after merging each branch
+- Commit and `git push` after every checkpoint update
+
+## Phase 0 — Foundation (you do this directly)
+
+1. Read the full aide — all CUJs, scenarios, invariants, constraints
+2. Build the shared foundation: data model, types, database schema, API interfaces
+3. Commit to main: `feat: foundation — data model, types, interfaces`
+4. Run `bantay check`
+5. Write `.bantay/builds/current.md` with Phase 0 complete
+6. Commit and `git push`
+7. `/compact` — shed Phase 0 context before planning Phase 1
+
+## For each subsequent phase
+
+### Plan (before spawning)
+
+For each CUJ in this phase (max 2):
+
+1. Read the CUJ scenarios from the aide
+2. Read the existing codebase to understand what's built
+3. Decompose into ordered implementation steps:
+   - Database schema / migrations needed
+   - API routes / server actions
+   - Core business logic
+   - UI components
+   - Integration between layers
+   - Tests mapped to each scenario
+4. Write the plan to `.bantay/plans/<cuj_id>.md`
+
+### Validate plan (before committing)
+
+Do not commit or spawn until every check passes.
+
+1. **Aide coverage** — Run `bantay aide show <cuj_id>`. Compare every
+   scenario's given/when/then against the plan. If a scenario is missing
+   or its acceptance criteria don't match, the plan is incomplete.
+
+2. **File references** — For every file, table, route, type, or function
+   the plan references, verify it exists: `ls`, `grep`, or `cat` the
+   actual path. If it doesn't exist and the plan doesn't say "create new",
+   the plan is hallucinated. Fix it.
+
+3. **Interface contracts** — For every function signature, API endpoint,
+   or type definition the plan depends on, read the actual source file
+   and confirm the signature matches. Don't trust your memory of Phase 0.
+   `cat` the file.
+
+4. **Dependency check** — Cross-reference the plan against `bantay tasks`.
+   If the plan assumes something built in a later phase or an unmerged
+   worktree, the plan has a forward dependency. Remove it or reorder.
+
+5. **Invariant coverage** — For every invariant linked to this CUJ's
+   scenarios (via `protected_by`), confirm the plan includes a step that
+   enforces or tests it. Missing invariant coverage = missing step.
+
+If any check fails, fix the plan and re-validate. Only after all 5 pass:
+commit the plan.
+
+### Spawn teammates (max 2)
+
+For each CUJ, spawn a teammate with this prompt:
+
+```
+You are building [CUJ feature] in worktree feat/[cuj-name].
+
+YOUR PLAN: Read .bantay/plans/[cuj_id].md — execute the steps in order.
+
+FIRST: Run bantay status to see what's already done. If scenarios
+are already covered, skip to the first uncovered one.
+
+BUILD RULES:
+- Use red/green TDD. Write the test, confirm it fails, implement.
+- Commit after each passing scenario.
+  Message: feat([cuj_name]): implement sc_[scenario_name]
+- Run bantay check after each commit.
+- Do not modify files outside your scope.
+
+CONTEXT MANAGEMENT:
+- After each scenario, check your context usage.
+- If over 50%, /compact before continuing.
+- If over 80%, commit everything and message the lead:
+  "Context full, requesting restart. Progress committed."
+
+If you hit a rate limit, wait and retry — don't abandon work.
+If something fails, commit what you have and message the lead.
+```
+
+### Monitor
+
+- Check teammate progress periodically
+- If a teammate goes silent for 10+ minutes, check its worktree:
+  ```
+  cd .worktrees/<teammate>
+  git log --oneline -5
+  bantay status
+  ```
+- If a teammate dies:
+  1. The plan survives in `.bantay/plans/<cuj_id>.md`
+  2. Committed work survives in the worktree
+  3. `bantay status` shows exactly what's done
+  4. Spawn a replacement with the same prompt — it reads the plan and status, picks up from the first incomplete step
+
+### Merge gate
+
+After both teammates complete:
+
+1. Merge both worktrees to main
+2. Run `bantay check` on main
+3. Run `bantay status`
+4. If checks fail, fix on main before proceeding
+5. Update `.bantay/builds/current.md`:
+   ```
+   phase: N
+   started: <timestamp>
+   completed_cujs:
+     - cuj_onboarding
+     - cuj_manage_artifact
+   in_progress: []
+   status: X/Y scenarios covered
+   ```
+6. Commit and `git push`
+7. `/compact` — shed this phase's context before the next one
+
+If remaining CUJs in this phase, plan and spawn the next 2.
+When phase complete, move to next phase.
+
+## If you (the lead) need to restart
+
+1. Read `.bantay/builds/current.md` — where we are
+2. Read `.bantay/plans/` — what was intended for each CUJ
+3. Run `bantay status` — what's actually built
+4. Check each active worktree with `git log`
+5. Resume orchestration from current state
+6. Respawn any teammates that were mid-work
+
+Nothing you know should exist only in your context window.
+If you die, a new lead reading these files is indistinguishable from you.
+
+## After all phases
+
+1. Run `bantay status` — should show all scenarios covered
+2. Run `bantay check` — should show all invariants passing
+3. Delete `.bantay/builds/current.md` — clean state
+4. Run `bantay aide lock` — snapshot the aide
+5. Commit and `git push`
+6. Report: phases completed, scenarios covered, invariants passing

package/src/templates/commands/bantay-status.md

@@ -0,0 +1,39 @@
+# Bantay Status
+
+Run `bantay status` and explain the results to the user.
+
+## What to Do
+
+1. Run the status command:
+```bash
+bantay status
+```
+
+2. Explain the output:
+   - How many scenarios are covered by tests
+   - Which scenarios are missing coverage
+   - Overall coverage percentage
+
+3. If coverage is low, suggest:
+   - Which scenarios should be prioritized for testing
+   - How to create tests that reference scenarios with `@scenario` tags
+
+## Understanding the Output
+
+The status command auto-discovers the .aide file in the current directory.
+
+The output shows:
+- **Covered**: Scenarios that have at least one test file referencing them via `@scenario sc_<name>`
+- **Uncovered**: Scenarios that exist in the .aide file but have no test coverage
+- **Coverage %**: Ratio of covered to total scenarios
+
+## Example Response
+
+"Your Bantay status shows 15/20 scenarios covered (75%).
+
+The uncovered scenarios are:
+- sc_checkout_payment_failed - No test for payment failure handling
+- sc_cart_item_out_of_stock - No test for inventory checks
+- ...
+
+I'd recommend prioritizing sc_checkout_payment_failed since payment handling is critical for user trust."