tribunal-kit 4.4.2 → 4.4.3

package/.agent/workflows/marathon.md

@@ -0,0 +1,247 @@
+---
+description: Long-running agent harness for multi-session projects. Decomposes specs into atomic features tracked in JSON, ensures clean handoffs between sessions, and provides structured progress tracking. Based on Anthropic's long-running agent patterns.
+---
+
+# /marathon — Long-Running Agent Harness
+
+$ARGUMENTS
+
+---
+
+## When to Use /marathon
+
+|Use `/marathon` when...|Use something else when...|
+|:---|:---|
+|A project requires multiple sessions to complete|Quick one-shot task → `/generate`|
+|You need structured progress tracking across context windows|Single feature addition → `/enhance`|
+|Building a complex app from a high-level spec|Planning without execution → `/plan`|
+|Previous agent sessions lost context or declared victory too early|Brainstorming options → `/brainstorm`|
+
+---
+
+## Sub-Commands
+
+```
+/marathon init [spec]       Start a new marathon from a specification
+/marathon continue          Resume work: read progress, pick next feature, implement
+/marathon status            Show progress dashboard
+/marathon reset             Archive current marathon and start fresh
+```
+
+---
+
+## Phase 1: Initialize (First Session Only)
+
+**Trigger:** `/marathon init "Build X"`
+
+This phase runs the **Initializer Agent** pattern — a specialized first session that sets up the foundation for all future sessions.
+
+### Steps
+
+1. **Parse the specification** — Read the user's spec carefully
+2. **Decompose into atomic features** — Generate 30–200 features depending on project complexity
+   - Each feature must be **independently testable**
+   - Each must have clear **done criteria** (verification steps)
+   - Group by category: `core`, `auth`, `ui`, `data`, `integration`, `polish`
+   - All features start with `passes: false`
+3. **Create the marathon state:**
+   ```bash
+   node .agent/scripts/marathon_harness.js init "Build X"
+   # Then add features one by one:
+   node .agent/scripts/marathon_harness.js add-feature "core" "User can open a new chat" "Navigate to main page" "Click New Chat" "Verify welcome state"
+   node .agent/scripts/marathon_harness.js add-feature "core" "User can type and send a message" "Open chat" "Type in input" "Press Enter" "See message appear"
+   # ... repeat for all features
+   ```
+4. **Scaffold the project** — Create initial files, install dependencies
+5. **Create init.sh** — Write a bootstrap script that starts the dev environment
+6. **Initial git commit:** `git commit -m "marathon: initial scaffold for [spec]"`
+7. **Human Gate:** User reviews the feature list before proceeding
+
+### Feature JSON Format
+
+Features are stored in `.agent/history/marathon/feature_list.json` as structured JSON. JSON is used instead of Markdown because agents are less likely to inappropriately modify JSON structures.
+
+```json
+{
+  "id": 1,
+  "category": "core",
+  "description": "User can open a new chat and see a welcome screen",
+  "steps": [
+    "Navigate to main page",
+    "Click 'New Chat' button",
+    "Verify welcome state renders"
+  ],
+  "passes": false,
+  "sessionCompleted": null
+}
+```
+
+> [!CAUTION]
+> **Feature descriptions are immutable.** After initialization, agents may ONLY change the `passes` field and `sessionCompleted` timestamp. It is unacceptable to remove, edit, or reorder features — this could lead to missing or buggy functionality.
+
+---
+
+## Phase 2: Get Bearings (Every Session Start)
+
+**Trigger:** `/marathon continue`
+
+Every new session starts by orienting the agent. This is the **Coding Agent** pattern — understanding state before making changes.
+
+### Steps
+
+1. **Read marathon state:**
+   ```bash
+   node .agent/scripts/marathon_harness.js session-start
+   ```
+   This automatically:
+   - Reads `progress.json` and shows what was done in previous sessions
+   - Reads `git log --oneline -20` for recent commits
+   - Shows the next unfinished feature
+   - Records the session start time
+
+2. **Start the dev environment:**
+   ```bash
+   node .agent/scripts/auto_preview.js start
+   ```
+
+3. **Smoke test basic functionality:**
+   - If a web app: navigate to the main page, verify it loads without errors
+   - If a CLI tool: run the help command, verify it outputs correctly
+   - If an API: hit the health check endpoint
+   - If browser MCP tools are available (Puppeteer), use them for visual verification
+
+4. **If smoke test fails:** Fix the broken state FIRST before implementing new features. The codebase must be clean before new work begins.
+
+5. **Announce bearings:**
+   ```
+   Session N. Progress: 12/47 features (25%).
+   Working on: Feature #13 [ui] — "User can toggle dark mode"
+   ```
+
+---
+
+## Phase 3: Implement (One Feature Per Cycle)
+
+Work on exactly **one feature at a time**. This incremental approach prevents the common failure mode of trying to do too much at once.
+
+### Steps
+
+1. **Impact analysis** — Identify files that will be affected (per `/enhance` workflow)
+2. **Implement the feature** — Write code, following Tribunal code quality standards
+3. **Self-verify the feature:**
+   - Run the verification steps listed in the feature's `steps` array
+   - Test as a human user would (browser for web, CLI for CLI)
+   - Run existing tests to ensure no regressions: `npm test` or equivalent
+4. **Mark as passing:**
+   ```bash
+   node .agent/scripts/marathon_harness.js mark <id> pass
+   ```
+5. **Git commit** with a descriptive message:
+   ```bash
+   git commit -m "marathon: implement feature #13 — dark mode toggle"
+   ```
+6. **Check context budget:**
+   - If context allows → return to Phase 2, step 5 (pick next feature)
+   - If nearing context limit → proceed to Phase 4
+
+### If a feature cannot be completed
+
+If a feature is blocked or too complex for the current session:
+1. Leave it as `passes: false`
+2. Add a log note explaining why:
+   ```bash
+   node .agent/scripts/marathon_harness.js log "Feature #13 blocked: requires OAuth integration not yet set up"
+   ```
+3. Move to the next feature or proceed to Phase 4
+
+---
+
+## Phase 4: Clean Exit (Session End)
+
+Every session MUST leave the codebase in a clean, merge-ready state.
+
+### Steps
+
+1. **Verify clean state:**
+   - All code compiles without errors
+   - All existing tests pass
+   - No half-implemented features left in an intermediate state
+   - If something is half-done, either complete it or revert it
+
+2. **Record session end:**
+   ```bash
+   node .agent/scripts/marathon_harness.js session-end "Implemented dark mode, user settings page, and notification bell"
+   ```
+
+3. **Final git commit:**
+   ```bash
+   git commit -m "marathon: session N complete, 15/47 features passing"
+   ```
+
+4. **Display status dashboard** — The session-end command automatically shows progress
+
+---
+
+## Marathon Guards
+
+```
+❌ Never delete or edit feature descriptions — only change the passes status
+❌ Never skip the smoke test at session start — broken code must be fixed first
+❌ Never mark a feature as passing without testing it end-to-end
+❌ Never work on more than one feature at a time
+❌ Never leave the codebase in a broken state at session end
+❌ Never declare the project "done" if any feature has passes: false
+❌ Never try to one-shot the entire project — always work incrementally
+❌ Never guess what happened in previous sessions — read progress.json and git log
+```
+
+---
+
+## State Files
+
+All marathon state is stored in `.agent/history/marathon/` (preserved on `tk update`):
+
+```
+.agent/history/marathon/
+├── feature_list.json    ← Structured feature backlog (immutable descriptions)
+├── progress.json        ← Session log + progress notes
+└── archive/             ← Previous marathons (after reset)
+```
+
+---
+
+## Script Reference
+
+```bash
+# Initialize
+node .agent/scripts/marathon_harness.js init "Build a task management app"
+
+# Add features (during init phase)
+node .agent/scripts/marathon_harness.js add-feature "core" "User can create a task" "Click add" "Type title" "Save"
+
+# Session lifecycle
+node .agent/scripts/marathon_harness.js session-start
+node .agent/scripts/marathon_harness.js session-end "Completed auth and dashboard"
+
+# During implementation
+node .agent/scripts/marathon_harness.js next
+node .agent/scripts/marathon_harness.js mark 5 pass
+node .agent/scripts/marathon_harness.js log "Refactored auth to use JWT"
+
+# Status
+node .agent/scripts/marathon_harness.js status
+
+# Archive and restart
+node .agent/scripts/marathon_harness.js reset
+```
+
+---
+
+## Usage Examples
+
+```
+/marathon init Build a full-stack clone of claude.ai with chat, settings, and themes
+/marathon continue
+/marathon status
+/marathon reset
+```

package/.agent/workflows/super-prompt.md

@@ -0,0 +1,27 @@
+# /super-prompt — Tokenless Prompt Compiler
+
+Converts conversational, fluffy requests into hyper-dense YAML structures that LLMs process perfectly, reducing prompt tokens and drastically improving response accuracy. **Zero API tokens are used during compilation.**
+
+## Usage
+
+Instead of typing your prompt into the AI chat directly, run the local compiler from your terminal:
+
+```bash
+node .agent/scripts/prompt_compiler.js "Hey, could you please build a login page using React and tailwind for me?"
+```
+
+## Expected Output
+
+The script strips conversational fillers and outputs a dense YAML block to your terminal instantly:
+
+```yaml
+---
+action: build
+target: login page using React and tailwind
+stack: [react, tailwind]
+---
+```
+
+## Next Step
+
+Copy the YAML output and paste it into the AI chat. The LLM will use this structured format to generate a highly accurate response while saving massive amounts of context window tokens!

package/bin/tribunal-kit.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 /**
  * tribunal-kit CLI (alias: tk)
  * 
@@ -743,6 +743,9 @@ async function runWithUpdateCheck(command, flags) {
         case 'context':
             cmdContext(flags);
             break;
+        case 'marathon':
+            cmdMarathon(flags);
+            break;
         case 'uninstall':
             cmdUninstall(flags);
             break;
@@ -956,6 +959,7 @@ function cmdHelp() {
     log(cmd('graph',    'Build and visualize the architecture graph'));
     log(cmd('mutate',   'Run the Mutation Engine to test test-suite reliability'));
     log(cmd('context',  'Retrieve a highly-optimized Context Snapshot for a file'));
+    log(cmd('marathon', 'Long-running agent harness (init, status, next, mark)'));
     log(cmd('hook',     'Install pre-push git hook for auto-learning'));
     log(cmd('uninstall','Remove .agent/ folder from project'));
     console.log();
@@ -994,12 +998,54 @@ function cmdHelp() {
     log(ex('tk case overrule --id 1'));
     log(ex('tk graph'));
     log(ex('tk mutate src/utils.js "npm test"'));
+    log(ex('tk marathon init "Build a todo app"'));
+    log(ex('tk marathon status'));
+    log(ex('tk marathon next'));
+    log(ex('tk marathon mark 5 pass'));
     log(ex('tk hook'));
     log(ex('tk uninstall'));
     console.log();
 }
 
 
+function cmdMarathon(flags) {
+    const targetDir = flags.path ? path.resolve(flags.path) : process.cwd();
+    const agentDest = path.join(targetDir, '.agent');
+
+    if (!fs.existsSync(agentDest)) {
+        err('.agent/ not found. Run: npx tribunal-kit init');
+        process.exit(1);
+    }
+
+    const args = process.argv.slice(3);
+    const argsStr = args.join(' ');
+    if (args.length === 0 || args[0] === 'help' || args[0] === '--help' || args[0] === '-h') {
+        banner();
+        log(`  ${c('cyan', '╔' + '═'.repeat(60) + '╗')}`);
+        log(`  ${c('cyan', '║')}${c('bold', c('white', '  Marathon — Long-Running Agent Harness                  '))}${c('cyan', '║')}`);
+        log(`  ${c('cyan', '╚' + '═'.repeat(60) + '╝')}`);
+        console.log();
+        log(`  ${c('cyan', 'init'.padEnd(16))}  ${c('gray', 'Start a new marathon (init "spec")')}`);
+        log(`  ${c('cyan', 'status'.padEnd(16))}  ${c('gray', 'Show progress dashboard')}`);
+        log(`  ${c('cyan', 'next'.padEnd(16))}  ${c('gray', 'Show next unfinished feature')}`);
+        log(`  ${c('cyan', 'mark'.padEnd(16))}  ${c('gray', 'Mark feature pass/fail (mark <id> pass)')}`);
+        log(`  ${c('cyan', 'log'.padEnd(16))}  ${c('gray', 'Add a progress note')}`);
+        log(`  ${c('cyan', 'session-start'.padEnd(16))}  ${c('gray', 'Begin a new work session')}`);
+        log(`  ${c('cyan', 'session-end'.padEnd(16))}  ${c('gray', 'End session with summary')}`);
+        log(`  ${c('cyan', 'add-feature'.padEnd(16))}  ${c('gray', 'Add feature: "category" "desc" "step1" ...')}`);
+        log(`  ${c('cyan', 'reset'.padEnd(16))}  ${c('gray', 'Archive and start fresh')}`);
+        console.log();
+        return;
+    }
+
+    const marathonScript = path.join(agentDest, 'scripts', 'marathon_harness.js');
+    try {
+        execSync(`node "${marathonScript}" ${argsStr}`, { stdio: 'inherit', cwd: targetDir });
+    } catch {
+        process.exit(1);
+    }
+}
+
 function cmdContext(flags) {
     const targetDir = flags.path ? path.resolve(flags.path) : process.cwd();
     const agentDest = path.join(targetDir, '.agent');

package/package.json

@@ -1,10 +1,11 @@
 {
     "name": "tribunal-kit",
-    "version": "4.4.2",
-    "description": "Anti-Hallucination AI Agent Kit — 40 specialist agents, 31 slash commands, 16 parallel Tribunal reviewers, Performance Swarm engine, and Supreme Court case law pipeline.",
+    "version": "4.4.3",
+    "description": "Anti-Hallucination AI Agent Kit — 40 specialist agents, 32 slash commands, 16 parallel Tribunal reviewers, Performance Swarm engine, Supreme Court case law pipeline, and long-running agent harness.",
     "keywords": [
         "ai",
         "ai-agent",
+        "long-running-agents",
         "agent",
         "agents",
         "multi-agent",