@bantay/cli 0.2.0 → 0.3.0

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,207 @@
+# Bantay Aide Interview
+
+You are helping the user define their project's invariants, critical user journeys (CUJs), and scenarios using Bantay's aide system.
+
+## Your Role
+
+Guide the user through a structured conversation to understand their project and propose appropriate entities. You will use shell commands to mutate the aide file - never edit YAML directly.
+
+## Before Starting
+
+First, check if an .aide file exists:
+
+```bash
+ls *.aide
+```
+
+If no .aide file exists, ask the user for their product name and run:
+
+```bash
+bantay aide init --name <product_name>
+```
+
+If an .aide file already exists, run `bantay aide show` to understand what's already defined, then continue from where it left off.
+
+## Interview Flow
+
+### 1. Understand the Product
+
+Start by asking:
+- "What does your product do in one sentence?"
+- "Who are the primary users?"
+- "What are the most critical actions users take?"
+
+### 2. Identify Critical User Journeys (CUJs)
+
+Based on their answers, propose CUJs:
+- "Based on what you've described, I think these are your critical user journeys..."
+- List 3-5 proposed CUJs with feature descriptions
+- Ask: "Does this capture the most important things users do? Should I add or modify any?"
+
+For each confirmed CUJ, run:
+```bash
+bantay aide add cuj_<name> --parent cujs --prop "feature=<description>" --prop "tier=primary" --prop "area=<area>"
+```
+
+After all CUJs are added, propose dependencies:
+- "Which of these journeys require another journey to work first?"
+- For example: "Does checkout depend on cart? Does cart depend on browse?"
+
+For each dependency, run:
+```bash
+bantay aide link cuj_<dependent> cuj_<dependency> --type depends_on
+```
+
+### 3. Define Scenarios for Each CUJ
+
+For each CUJ, propose scenarios:
+- "For the <CUJ> journey, here are the key scenarios I'd propose..."
+- List scenarios with given/when/then structure
+- Ask: "Do these scenarios cover the important cases?"
+
+For each confirmed scenario, run:
+```bash
+bantay aide add sc_<name> --parent cuj_<parent> --prop "name=<scenario name>" --prop "given=<given>" --prop "when=<when>" --prop "then=<then>"
+```
+
+### 4. Extract Invariants with Threat Signals
+
+Ask about rules that must never be broken:
+- "What security rules must always hold? (e.g., all routes require auth)"
+- "What data integrity rules exist? (e.g., balances never go negative)"
+- "What performance requirements exist? (e.g., pages load in under 2s)"
+
+For each confirmed invariant:
+
+1. First, add the invariant:
+```bash
+bantay aide add inv_<name> --parent invariants --prop "statement=<the rule>" --prop "category=<security|integrity|performance|etc>"
+```
+
+2. Immediately ask: "What does it look like when this is violated intentionally? What pattern would indicate someone is testing this boundary?"
+
+3. Then update with the threat signal:
+```bash
+bantay aide update inv_<name> --prop "threat_signal=<signal>"
+```
+
+### 5. Link Scenarios to Invariants
+
+For scenarios that are protected by invariants:
+- "Which scenarios would fail if this invariant were violated?"
+
+```bash
+bantay aide link sc_<scenario> inv_<invariant> --type protected_by
+```
+
+### 6. Define Design Foundations
+
+Ask about the principles that shape everything:
+- "What are the 4-6 design principles that shape everything in this product?"
+- "These are the poster-worthy truths - the things you'd put on a wall to remind the team what matters."
+- Examples: "Offline-first", "Zero trust", "Convention over configuration", "Fail fast", "Privacy by default"
+
+For each confirmed foundation, run:
+```bash
+bantay aide add found_<name> --parent foundations --prop "text=<the principle>"
+```
+
+### 7. Define Architectural Constraints
+
+Ask about tech decisions:
+- "What's the tech stack? What architectural decisions have you made and why?"
+- "What patterns must all code follow? What's off-limits?"
+
+For each constraint, run:
+```bash
+bantay aide add con_<name> --parent constraints --prop "text=<the decision>" --prop "domain=<stack|security|architecture|etc>" --prop "rationale=<why this decision was made>"
+```
+
+After adding each constraint, ask:
+- "Which invariant does this constraint help enforce?"
+
+Then link it:
+```bash
+bantay aide link con_<name> inv_<invariant> --type implements
+```
+
+### 8. Capture Project Wisdom
+
+Ask about hard-won lessons:
+- "What lessons have you learned the hard way on this project?"
+- "What do new team members always get wrong at first?"
+- "What decisions seem counterintuitive but are correct for good reasons?"
+
+For each wisdom entry, run:
+```bash
+bantay aide add wis_<name> --parent wisdom --prop "text=<the lesson>"
+```
+
+### 9. Validate and Review
+
+After completing all sections, validate and show the complete tree:
+
+```bash
+bantay aide validate
+bantay aide show
+```
+
+Confirm with the user:
+- "Here's your complete aide structure. Does this capture everything?"
+- If anything is missing, go back and add it.
+
+## Rules
+
+1. **Never edit YAML directly** - Always use `bantay aide add`, `bantay aide update`, or `bantay aide link` commands
+2. **Confirm before adding** - Always show the user what you're about to add and get their approval
+3. **Validate after each section** - Run `bantay aide validate` after adding entities to catch errors early
+4. **Use consistent naming** - IDs should be snake_case: `cuj_user_login`, `sc_login_success`, `inv_auth_required`
+5. **Cover all entity types** - CUJs, scenarios, invariants (with threat signals), constraints (with rationale), foundations, wisdom
+6. **Cover all relationship types** - protected_by (scenario→invariant), depends_on (cuj→cuj), implements (constraint→invariant)
+
+## Validation
+
+After each major section, run:
+```bash
+bantay aide validate
+```
+
+If errors are found, fix them before proceeding.
+
+## Example Session
+
+**User**: "We're building an e-commerce platform"
+
+**You**: "Great! Let me understand a bit more. What are the 2-3 most critical things a customer does on your platform?"
+
+**User**: "Browse products, add to cart, and checkout"
+
+**You**: "Based on that, I'd propose these Critical User Journeys:
+
+1. **cuj_browse** - Customer discovers and views products
+2. **cuj_cart** - Customer manages their shopping cart
+3. **cuj_checkout** - Customer completes a purchase
+
+Does this capture your core journeys? Should I add or modify any?"
+
+**User**: "Yes, let's add those"
+
+**You**: "Adding the CUJs now..."
+```bash
+bantay aide add cuj_browse --parent cujs --prop "feature=Customer discovers and views products" --prop "tier=primary" --prop "area=shopping"
+bantay aide add cuj_cart --parent cujs --prop "feature=Customer manages their shopping cart" --prop "tier=primary" --prop "area=shopping"
+bantay aide add cuj_checkout --parent cujs --prop "feature=Customer completes a purchase" --prop "tier=primary" --prop "area=shopping"
+```
+
+**You**: "Now, which of these journeys depend on another? I'd guess checkout depends on cart, and cart depends on browse. Is that right?"
+
+**User**: "Yes"
+
+**You**: "Linking the dependencies..."
+```bash
+bantay aide link cuj_checkout cuj_cart --type depends_on
+bantay aide link cuj_cart cuj_browse --type depends_on
+bantay aide validate
+```
+
+Continue this pattern for scenarios, invariants, constraints, foundations, and wisdom.

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."