openfleet 0.1.0 → 0.3.0

package/dist/templates/.openfleet/README.md

@@ -8,7 +8,7 @@ not for humans, though it would be difficult to mess this up unintentionally.
 
 ## For Agents 🤖
 
-Understand `## Structure`, then see `./status/current.md`, and other necessary
+Understand `## Structure`, then see `./status.md`, and other necessary
 files before starting your current task.
 
 ## Structure
@@ -16,36 +16,51 @@ files before starting your current task.
 ```
 .openfleet/
 ├── README.md
-├── status/
-│   ├── current.md         # Anchor point - agent reads this first
+├── status.md                # Anchor point - agent reads this first (gitignored)
+├── agents/                  # Per-agent scratchpads (gitignored)
+│   ├── Zeus.md
+│   ├── Athena.md
+│   ├── Apollo.md
+│   ├── Hercules.md
+│   ├── Chiron.md
+│   └── Mnemosyne.md
+├── sessions/                # Agent transcripts / journals (gitignored)
+├── stories/                 # Work organized by story/epic (gitignored)
+├── docs/                    # Permanent documentation (committed)
 │   └── README.md
-├── sessions/              # Agent transcripts / journals
-│   └── README.md
-├── stories/               # Work organized by story/epic
-│   ├── README.md
-│   └── unassigned/
-│       └── README.md
-├── docs/
-│   ├── README.md
-│   └── working/           # Agent scratch space
-│       └── README.md
-├── experience/            # Self-healing long term memory
-│   ├── README.md
-│   ├── Mnemosyne.md
-│   ├── runbooks/          # Used for recurring tasks, like Claude Agent Skills
-│   ├── troubleshooting/   # Used for common errors
-│   ├── lessons/           # Used for learning from past mistakes
-│   └── blunders/          # Used for learning from stupid mistakes
-├── standards/
-│   ├── README.md
+├── experience/              # Self-healing long term memory (committed)
+│   ├── runbooks/            # Used for recurring tasks
+│   ├── troubleshooting/     # Used for common errors
+│   ├── lessons/             # Used for learning from past mistakes
+│   └── blunders/            # Used for learning from stupid mistakes
+├── standards/               # Prescriptive guidelines (committed)
 │   ├── code-style.md
 │   ├── architecture.md
 │   ├── testing.md
 │   └── review-checklist.md
-└── reviews/               # Human review artifacts
+└── reviews/                 # Human review artifacts (committed)
     └── README.md
 ```
 
+## Git worktree visualization
+
+```
+main/dev
+ │
+ └──► feat/<story>
+       │
+       ├──► feat/<story>/<task>
+       │     │
+       │     └──► feat/<story>/<task>/<branch>
+       │
+       ╰─────● PR raised for review
+
+Legend:
+- `├──►` branch created
+- `╰─────●` resolved (merged back to parent)
+- `╰─────` escalated (became sibling story)
+```
+
 ## Flexibility
 
 This template is a _general_ guide for project management. Feel free to customize

package/dist/templates/.openfleet/agents/Apollo.md

@@ -0,0 +1,10 @@
+# Apollo
+
+_God of music, poetry, and prophecy._
+
+Your personal scratchpad. Use this for:
+
+- Design patterns that worked well
+- Estimation accuracy notes
+- HLD/LLD templates worth reusing
+- Architecture decisions and rationale

package/dist/templates/.openfleet/agents/Athena.md

@@ -0,0 +1,10 @@
+# Athena
+
+_Goddess of wisdom and strategic warfare._
+
+Your personal scratchpad. Use this for:
+
+- Research patterns that worked well
+- Useful search queries and codebase landmarks
+- Notes on documentation sources
+- Patterns discovered during exploration

package/dist/templates/.openfleet/agents/Chiron.md

@@ -0,0 +1,10 @@
+# Chiron
+
+_Wisest of the centaurs, teacher of heroes._
+
+Your personal scratchpad. Use this for:
+
+- Common review findings
+- Code style preferences observed
+- Patterns worth enforcing
+- Review checklist additions

package/dist/templates/.openfleet/agents/Hercules.md

@@ -0,0 +1,10 @@
+# Hercules
+
+_Divine hero known for strength and endurance._
+
+Your personal scratchpad. Use this for:
+
+- Commands and scripts that worked
+- Environment quirks and workarounds
+- Debugging approaches that helped
+- Build/test configurations

package/dist/templates/.openfleet/agents/Zeus.md

@@ -0,0 +1,12 @@
+# Zeus
+
+_King of the gods, ruler of Mount Olympus._
+
+Your personal scratchpad. Use this for:
+
+- Pending decisions awaiting user input
+- User preferences observed during sessions
+- Notes on agent performance and coordination
+
+Do NOT use this for public information - use `status.md` instead,
+where other agents can see it as well.

package/dist/templates/.openfleet/docs/README.md

@@ -1,51 +1,51 @@
 # Documentation Directory
 
-Design documents and working notes.
+Permanent documentation and compressed story learnings.
 
 ## Structure
 
 ```
 docs/
-├── README.md              # This file
-├── adr/                   # Architecture decision records
+├── README.md               # This file
+├── <story-name>.md         # Compressed learnings (auto-generated by Zeus)
+├── adr/                    # Architecture decision records (optional)
 │   └── 001-use-postgres.md
-├── guides/                # How-to guides for humans
-│   └── local-development.md
-└── working/               # Agent scratch space for drafts
-    └── <document-name>.md
+└── guides/                 # How-to guides for humans (optional)
+    └── local-development.md
 ```
 
-## File naming
+## Story Documentation Format
 
-Use lowercase kebab-case:
+After a story completes, Zeus writes `<story-name>.md`:
 
-- `openfleet-v2-hld.md`
-- `auth-redesign-proposal.md`
-- `api-migration-plan.md`
+```markdown
+# <Story Name>
 
-## Usage
+**Completed**: YYYY-MM-DD
+**PR**: #XX (if applicable)
 
-The `working/` directory is for temporary documents being drafted by agents.
-Once finalized, move docs to appropriate directories under `docs/` or `stories/`.
+## Summary
 
-## Format
+<1-2 paragraph overview>
 
-Working documents are freeform, but commonly include:
+## Task Tree
 
-```markdown
-# <Document title>
+<Git tree visualization>
 
-## Overview
+## Key Decisions
 
-<Brief description of what this document covers>
+| Decision | Choice | Rationale |
+| -------- | ------ | --------- |
 
-## <Section 1>
+## Learnings
 
-<Content>
+- <Insight 1>
+- <Insight 2>
+```
 
-## <Section 2>
+## File Naming
 
-<Content>
-```
+Use lowercase kebab-case:
 
-For design docs specifically (HLD/LLD), see the story task format in `stories/README.md`.
+- `auth-redesign.md`
+- `openfleet-branching-model.md`

package/dist/templates/.openfleet/experience/README.md

@@ -6,7 +6,6 @@ Self-healing systems with long-term memory. Learned knowledge from past work.
 
 ```
 experience/
-├── Mnemosyne.md           # Ignore unless you're the Reflect agent
 ├── runbooks/              # How-to guides for recurring tasks
 ├── troubleshooting/       # Problem → solution mappings
 ├── lessons/               # Insights and best practices

package/dist/templates/.openfleet/gitignore.template

@@ -0,0 +1,7 @@
+# .openfleet
+agents/
+stories/
+status.md
+sessions/
+transcripts/
+openfleet.log

package/dist/templates/.openfleet/status.md

@@ -0,0 +1,31 @@
+# Status
+
+Shared anchor point for all agents. Read this first before starting any task.
+
+## Current Position
+
+**Story**: _None_
+**Branch**: `main`
+**Task**: _None_
+
+## Context Files
+
+_No active story - nothing to read yet._
+
+## Git Tree
+
+```
+main ← you are here
+```
+
+## Instructions
+
+_No active instructions._
+
+## Blocked
+
+_Nothing blocked._
+
+## Notes
+
+_No notes._

package/dist/templates/.openfleet/stories/README.md

@@ -1,86 +1,197 @@
 # Stories Directory
 
-Work organized by story (epic-level grouping).
+Working tree for active stories. **This directory is gitignored.**
 
 ## Structure
 
 ```
 stories/
-├── README.md                           # This file
-├── YYYY-WXX/                           # Week-based organization
-│   └── <story-name>/
-│       ├── README.md                   # Story overview
-│       └── tasks/
-│           └── MM-DD_<task-name>/
-│               ├── Research.md         # Scout the topic
-│               ├── HLD.md              # High-level design
-│               └── LLD.md              # Low-level design
-└── unassigned/                         # Tasks without a story
+├── README.md                      # This file
+└── <story-name>/
+    ├── README.md                  # Story overview, goals
+    ├── Research.md                # Scout's findings
+    ├── HLD.md                     # High-level design
+    ├── LLD.md                     # Low-level design
+    ├── Implementation.md          # Actor's report
+    └── tasks/
+        └── <MM-DD_task-name>/
+            ├── README.md          # Task overview
+            ├── Research.md
+            ├── HLD.md
+            ├── LLD.md
+            ├── Implementation.md
+            └── branches/          # For discovered issues
+                └── <branch-name>/
+                    ├── README.md
+                    ├── Research.md
+                    ├── HLD.md
+                    ├── LLD.md
+                    ├── Implementation.md
+                    └── branches/  # Recursive (unlimited depth)
 ```
 
-## Naming conventions
+## Naming Conventions
 
-- **Week directories**: `YYYY-WXX` (e.g., `2026-W01`)
-- **Story directories**: lowercase kebab-case (e.g., `auth-redesign`, `openfleet-v2`)
-- **Task directories**: `MM-DD_<task-name>` (e.g., `01-03_implement-save-conversation`)
+- **Story directories**: lowercase kebab-case (`auth-redesign`, `openfleet-v2`)
+- **Task directories**: `MM-DD_<task-name>` (month-day, e.g. `01-05_jwt-validation` for Jan 5)
+- **Branch directories**: lowercase kebab-case (`fix-expiry`, `add-caching`)
 
-## Usage
+## Git Alignment
 
-Stories group related tasks under a common theme or epic.
-Use week-based directories to organize by time period.
+File system paths map to git branches:
 
-## Story README format
+| Path                                                        | Git Branch                                                     |
+| ----------------------------------------------------------- | -------------------------------------------------------------- |
+| `stories/agent-harness-hardening/`                          | `feat/agent-harness-hardening`                                 |
+| `stories/agent-harness-hardening/tasks/01-05_plugin-hooks/` | `feat/agent-harness-hardening/plugin-hooks`                    |
+| `stories/.../branches/fix-opencode-hooks/`                  | `feat/agent-harness-hardening/plugin-hooks/fix-opencode-hooks` |
 
-```markdown
-# <Story name>
-
-## Goal
-
-<What this story aims to accomplish>
+## Branch Complexity Tiers
 
-## Tasks
+When Zeus discovers an issue mid-task:
 
-- [ ] <Task 1>
-- [ ] <Task 2>
+| Tier    | Criteria              | Action                         |
+| ------- | --------------------- | ------------------------------ |
+| Trivial | <10 lines, obvious    | Actor fixes inline             |
+| Medium  | Needs investigation   | Create `branches/`, mini-SPARR |
+| Hard    | Cross-cutting concern | Escalate to sibling story      |
 
-## Status
+## Story Lifecycle
 
-<Current status: planning | in-progress | completed>
-```
+1. Zeus creates story directory + git branch
+2. SPARR cycle: Scout → Planner → Actor → Reviewer → Reflector
+3. If issue discovered: assess tier, branch if needed
+4. On completion: Zeus compresses to `docs/<story>.md`
+5. Working files can be deleted (gitignored anyway)
 
-## Task HLD format
+## Story README Format
 
 ```markdown
-# <Task name> - High Level Design
+# <Story Name>
 
-## Problem
+**Created**: YYYY-MM-DD
+**Status**: planning | in_progress | completed
+**Branch**: feat/<story-name>
+
+## Goal
 
-<What problem does this solve>
+<What this story aims to accomplish>
 
-## Solution
+## Tasks
 
-<High-level approach>
+- [ ] <Task 1>
+- [x] <Task 2> ← completed
 
-## Scope
+## Git Tree
 
-- <What's included>
-- <What's excluded>
+<Current branch topology - maintained by Zeus>
 ```
 
-## Task LLD format
+## Example: Complete Story with Branches
 
-```markdown
-# <Task name> - Low Level Design
+This example demonstrates a real story with nested branches, escalation, and resolution.
 
-## Implementation
+### File System Structure
 
-<Detailed technical approach>
+```
+stories/
+└── agent-harness-hardening/
+    ├── README.md
+    ├── Research.md
+    ├── HLD.md
+    ├── LLD.md
+    └── tasks/
+        ├── 01-05_plugin-hooks/
+        │   ├── README.md
+        │   ├── Research.md
+        │   ├── HLD.md
+        │   ├── LLD.md
+        │   └── branches/
+        │       └── fix-opencode-hooks/
+        │           ├── README.md
+        │           ├── Research.md      ← mini-SPARR
+        │           ├── HLD.md
+        │           ├── LLD.md
+        │           └── branches/
+        │               └── add-hook-regression-tests/    ← nested branch (2 levels deep)
+        │                   ├── README.md
+        │                   ├── Research.md
+        │                   └── LLD.md
+        │
+        ├── 01-07_transcript-pipeline/
+        │   ├── README.md
+        │   ├── Research.md
+        │   ├── HLD.md
+        │   ├── LLD.md
+        │   └── branches/
+        │       └── add-browser-mcp/     ← escalated to sibling story
+        │           ├── README.md
+        │           └── Research.md      ← Scout found it's too big
+        │
+        └── 01-09_tool-registry/
+            ├── README.md
+            ├── Research.md
+            ├── HLD.md
+            └── LLD.md                   ← simple task, no branches needed
+```
 
-## Files to modify
+### Corresponding Git Tree
 
-- `path/to/file.ts`: <changes>
+```
+main
+ │
+ ├──► feat/agent-harness-hardening                              a1b2c3d start agent harness hardening
+ │     │
+ │     ├──► feat/agent-harness-hardening/plugin-hooks           b2c3d4e harden opencode plugin hooks
+ │     │     │
+ │     │     ├──► feat/agent-harness-hardening/plugin-hooks/fix-opencode-hooks
+ │     │     │     │                                            c3d4e5f fix hook edge case
+ │     │     │     │
+ │     │     │     ├──► feat/agent-harness-hardening/plugin-hooks/fix-opencode-hooks/add-hook-regression-tests
+ │     │     │     │     │                                      d4e5f6g add regression test coverage
+ │     │     │     │     │
+ │     │     │     ╰─────●                                      ← resolved (merged to fix-opencode-hooks)
+ │     │     │     │
+ │     │     │     └── e5f6g7h tests passing
+ │     │     │
+ │     │     ╰─────●                                            ← resolved (merged to plugin-hooks)
+ │     │     │
+ │     │     └── f6g7h8i hook hardening complete
+ │     │
+ │     ╰─────●                                                  ← resolved (merged to agent-harness-hardening)
+ │     │
+ │     ├──► feat/agent-harness-hardening/transcript-pipeline    g7h8i9j implement transcript pipeline
+ │     │     │
+ │     │     ├──► feat/agent-harness-hardening/transcript-pipeline/add-browser-mcp
+ │     │     │     │                                            h8i9j0k scout browser mcp integration
+ │     │     │     │
+ │     │     ╰─────✕                                            ← escalated to feat/browser-mcp-integration
+ │     │     │
+ │     │     └── i9j0k1l transcript pipeline (sans browser mcp)
+ │     │
+ │     ╰─────●                                                  ← resolved (merged to agent-harness-hardening)
+ │     │
+ │     ├──► feat/agent-harness-hardening/tool-registry          j0k1l2m implement tool registry
+ │     │     │
+ │     │     └── k1l2m3n tool registry complete
+ │     │
+ │     ╰─────●                                                  ← resolved (merged to agent-harness-hardening)
+ │     │
+ │     └── l2m3n4o agent harness hardening complete
+ │
+ ╰─────● PR #47 merged to main
+
+
+stories/browser-mcp-integration/                               ← sibling story (escalated from transcript-pipeline)
+└──► feat/browser-mcp-integration                              m3n4o5p start browser mcp integration
+      │
+      └── (in progress...)
+```
 
-## Testing
+### Legend
 
-<How to verify the implementation>
-```
+| Symbol    | Meaning                          |
+| --------- | -------------------------------- |
+| `├──►`    | Branch created                   |
+| `╰─────●` | Resolved (merged back to parent) |
+| `╰─────✕` | Escalated (became sibling story) |

package/dist/templates/.openfleet/transcripts/README.md

@@ -0,0 +1,30 @@
+# Transcripts Directory
+
+Human-readable Markdown transcripts of agent sessions.
+
+## Format
+
+Each session is stored as `{sessionID}.md` with entries:
+
+- **User Message**: User messages with timestamp and content
+- **Tool Use**: Tool invocations with call ID and input
+- **Tool Result**: Tool outputs with input, output, and metadata
+
+Entries are separated by `---` for readability.
+
+## Subagent Transcripts
+
+Subagent transcripts are stored in `{parentSessionID}/{subagentSessionID}.md`.
+
+## Usage
+
+```bash
+# View full transcript
+cat .openfleet/transcripts/{sessionID}.md
+
+# Search for tool calls
+grep "## Tool Use:" .openfleet/transcripts/{sessionID}.md
+
+# Count tool calls
+grep -c "## Tool Use:" .openfleet/transcripts/{sessionID}.md
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openfleet",
-  "version": "0.1.0",
-  "description": "SPAR framework agents + infinite context for OpenCode",
+  "version": "0.3.0",
+  "description": "SPARR framework agents + infinite context for OpenCode",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,7 +19,7 @@
     "url": "git+https://github.com/scottsus/openfleet.git"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean && cp -r src/templates dist/",
+    "build": "rm -rf dist && tsup src/index.ts --format esm --dts && cp -r src/templates dist/",
     "dev": "tsup src/index.ts --format esm --dts --watch",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write .",

package/dist/templates/.openfleet/docs/working/README.md

@@ -1,5 +0,0 @@
-# Working Documents
-
-Agent scratch space for drafts and work-in-progress documents.
-
-Files here are temporary. Move finalized docs to appropriate story directories.

package/dist/templates/.openfleet/status/README.md

@@ -1,15 +0,0 @@
-# Status Directory
-
-The anchor point for agent context. Always read `current.md` first.
-
-## Files
-
-- `current.md`: Current work status, active story, recent sessions
-
-## Usage
-
-All agents will read this file on startup for working context.
-
-## Git commit preference
-
-_Undecided between **submit as PR** or **NEVER MAKE ANY COMMITS**_

package/dist/templates/.openfleet/status/current.md

@@ -1,29 +0,0 @@
-# Current Status
-
-**Last Updated**: 2026-01-04T04:09:33.840Z
-**Active Story**: _none_
-**Status**: idle
-
-## Current Work
-
-_No active work._
-
-## Active Tasks
-
-_None._
-
-## Recent Sessions
-
-- `001_investigate-openfleet-directory.md` (2026-01-04) [188 messages, 74.5K tokens] ← current session
-
----
-
-## Quick Stats
-
-- Sessions today: 1
-- Sessions this week: 1
-- Last housekeeping: 2026-01-04T04:10:15Z
-
----
-
-_Updated by agents and tools automatically._

package/dist/templates/.openfleet/stories/unassigned/README.md

@@ -1,40 +0,0 @@
-# Unassigned Tasks
-
-Tasks that don't belong to a specific story.
-
-## Structure
-
-```
-unassigned/
-├── README.md                    # This file
-└── MM-DD_<task-name>/
-    ├── HLD.md                   # High-level design (optional for small tasks)
-    └── LLD.md                   # Low-level design (optional for small tasks)
-```
-
-## Usage
-
-Place standalone tasks here that are:
-
-- Quick fixes
-- One-off requests
-- Not part of a larger initiative
-
-Move to a story directory when they become part of a larger effort.
-
-## When to skip HLD/LLD
-
-For trivial tasks (< 1 hour of work), a single `notes.md` is sufficient:
-
-```markdown
-# <Task name>
-
-## What
-
-<Brief description>
-
-## Changes
-
-- <Change 1>
-- <Change 2>
-```