openfleet 0.3.15 → 0.4.0

package/dist/templates/.openfleet/.templates/task-tree.md

@@ -64,7 +64,7 @@ feat/auth-redesign
  ├──► task/06-10_refresh-tokens (created 2026-01-19) ← YOU ARE HERE
  │     Phases: R✅ H✅ L🔄 I⏳
  │     Branch: feat/auth-redesign/refresh-tokens
- │     Agent: Apollo (reviewing LLD.md)
+ │     Agent: Architect (reviewing LLD.md)
  │     │
  │     └──► branch/temp-skip-rotation (created 2026-01-20) ⏸️ escalated
  │           Issue: Complex token rotation bug
@@ -76,7 +76,7 @@ feat/auth-redesign
 
 ---
 
-## Instructions for Zeus
+## Instructions for Orchestrator
 
 **CRITICAL**: Update this file after EVERY change to THIS story:
 
@@ -91,7 +91,7 @@ The tree MUST show:
 
 1. Full hierarchy (task → subtask → branches)
 2. Current position marker (`← YOU ARE HERE`)
-3. Active agents (`← Hercules working`)
+3. Active agents (`← Builder working`)
 4. Phase progress for each node (R/H/L/I with status)
 5. Branch status (merged, blocked, escalated)
 6. Git branch names

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.md`, and other necessary
+Understand `## Structure`, then see `./private/status.md`, and other necessary
 files before starting your current task.
 
 ## Structure
@@ -16,30 +16,33 @@ files before starting your current task.
 ```
 .openfleet/
 ├── README.md
-├── 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
-├── 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 (committed)
-    └── README.md
+├── VERSION                  # Stamped on init; absence/mismatch = migration needed
+├── migrations/              # Per-version migration guides
+│   └── 0.4.0.md
+├── .templates/              # Templates for new stories/tasks
+│   └── task-tree.md
+├── public/                  # Committed — shared knowledge
+│   ├── docs/                # Compressed story learnings
+│   ├── standards/           # Prescriptive guidelines
+│   │   ├── code-style.md
+│   │   ├── architecture.md
+│   │   ├── testing.md
+│   │   └── review-checklist.md
+│   └── troubleshooting/     # Common error guides
+└── private/                 # Gitignored — machine-local
+    ├── status.md            # Anchor point - agent reads this first
+    ├── agents/              # Per-agent scratchpads
+    │   ├── Zeus.md
+    │   ├── Recon.md
+    │   ├── Architect.md
+    │   ├── Builder.md
+    │   ├── Validator.md
+    │   └── Introspector.md
+    ├── stories/             # Work organized by story/epic
+    ├── experience/          # Self-healing long term memory
+    │   ├── runbooks/        # Used for recurring tasks
+    │   └── lessons/         # Used for learning from past mistakes and pitfalls
+    └── transcripts/         # Agent session transcripts
 ```
 
 ## Git worktree visualization

package/dist/templates/.openfleet/VERSION

@@ -0,0 +1 @@
+0.4.0

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

@@ -1,7 +1,2 @@
-# .openfleet
-agents/
-stories/
-status.md
-sessions/
-transcripts/
-openfleet.log
+# private/ is machine-local and not committed
+private/

package/dist/templates/.openfleet/migrations/0.4.0.md

@@ -0,0 +1,74 @@
+# Migration Guide: v0.4.0
+
+## What Changed
+
+- Directory restructured into `public/` (committed) and `private/` (gitignored)
+- Agent files renamed: Athena→Recon, Apollo→Architect, Hercules→Builder, Chiron→Validator, Mnemosyne→Introspector
+- `sessions/` and `reviews/` removed
+
+## Migration Steps
+
+Run these commands from inside your `.openfleet/` directory:
+
+```bash
+# 1. Create new structure
+mkdir -p private/agents private/stories private/experience/runbooks private/experience/lessons private/transcripts
+mkdir -p public/docs public/standards public/troubleshooting
+
+# 2. Move agent files (with renames)
+[ -f agents/Athena.md ]    && mv agents/Athena.md    private/agents/Recon.md
+[ -f agents/Apollo.md ]    && mv agents/Apollo.md    private/agents/Architect.md
+[ -f agents/Hercules.md ]  && mv agents/Hercules.md  private/agents/Builder.md
+[ -f agents/Chiron.md ]    && mv agents/Chiron.md    private/agents/Validator.md
+[ -f agents/Mnemosyne.md ] && mv agents/Mnemosyne.md private/agents/Introspector.md
+[ -f agents/Zeus.md ]      && mv agents/Zeus.md      private/agents/Zeus.md
+[ -d agents ]              && rmdir agents 2>/dev/null
+
+# 3. Move structural dirs
+[ -d stories ]     && mv stories     private/stories
+[ -f status.md ]   && mv status.md   private/status.md
+[ -d transcripts ] && mv transcripts private/transcripts
+
+# 4. Move experience subdirs
+[ -d experience/runbooks ]        && mv experience/runbooks        private/experience/runbooks
+[ -d experience/lessons ]         && mv experience/lessons         private/experience/lessons
+[ -d experience/troubleshooting ] && mv experience/troubleshooting public/troubleshooting
+
+# 5. Move public dirs
+[ -d docs ]      && mv docs      public/docs
+[ -d standards ] && mv standards public/standards
+
+# 6. Clean up
+rm -rf sessions reviews 2>/dev/null
+rmdir experience 2>/dev/null
+
+# 7. Update .gitignore
+echo "private/" > .gitignore
+
+# 8. Stamp version
+echo "0.4.0" > VERSION
+```
+
+## Verify
+
+After migration, your `.openfleet/` should look like:
+
+```
+.openfleet/
+├── VERSION
+├── .gitignore        # contains: private/
+├── README.md
+├── .templates/
+├── migrations/
+│   └── 0.4.0.md
+├── public/
+│   ├── docs/
+│   ├── standards/
+│   └── troubleshooting/
+└── private/
+    ├── status.md
+    ├── agents/
+    ├── stories/
+    ├── experience/
+    └── transcripts/
+```

package/dist/templates/.openfleet/{agents/Apollo.md → private/agents/Architect.md}

@@ -1,6 +1,6 @@
-# Apollo
+# Architect
 
-_God of music, poetry, and prophecy._
+_Architecture and planning agent._
 
 Your personal scratchpad. Use this for:
 

package/dist/templates/.openfleet/{agents/Hercules.md → private/agents/Builder.md}

@@ -1,6 +1,6 @@
-# Hercules
+# Builder
 
-_Divine hero known for strength and endurance._
+_Implementation and execution agent._
 
 Your personal scratchpad. Use this for:
 

package/dist/templates/.openfleet/{agents/Mnemosyne.md → private/agents/Introspector.md}

@@ -1,6 +1,6 @@
-# Mnemosyne
+# Introspector
 
-_The goddess of memory and mother of the Muses._
+_Knowledge management and reflection agent._
 
 This is the index of accumulated experience. Consult before tackling unfamiliar problems.
 
@@ -20,10 +20,6 @@ _No guides yet._
 
 _No lessons yet._
 
-### Blunders to Avoid
-
-_No blunders recorded._
-
 ---
 
 ## File Naming Conventions
@@ -52,14 +48,6 @@ Use lowercase kebab-case with suffix: `<topic>-lesson.md`
 - `batch-database-queries-lesson.md`
 - `early-return-pattern-lesson.md`
 
-### Blunders
-
-Use lowercase kebab-case with suffix: `<descriptive-name>-blunder.md`
-
-- `api-key-exposure-blunder.md`
-- `missing-null-check-blunder.md`
-- `wrong-environment-deploy-blunder.md`
-
 ---
 
 ## Templates
@@ -139,32 +127,6 @@ Use lowercase kebab-case with suffix: `<descriptive-name>-blunder.md`
 - <Links to relevant docs, code, or external resources>
 ```
 
-### Blunder
-
-```markdown
-# <Brief title describing the blunder>
-
-## What happened
-
-<Description of the mistake - what was done wrong>
-
-## Impact
-
-<What went wrong as a result - consequences>
-
-## Root cause
-
-<Why it happened - the underlying reason>
-
-## Prevention
-
-<How to avoid this in the future - proactive measures>
-
-## Detection
-
-<How to catch early if it happens again - monitoring/review steps>
-```
-
 ---
 
 _Updated when new experience is captured._

package/dist/templates/.openfleet/{agents/Athena.md → private/agents/Recon.md}

@@ -1,6 +1,6 @@
-# Athena
+# Recon
 
-_Goddess of wisdom and strategic warfare._
+_Reconnaissance and research agent._
 
 Your personal scratchpad. Use this for:
 

package/dist/templates/.openfleet/{agents/Chiron.md → private/agents/Validator.md}

@@ -1,6 +1,6 @@
-# Chiron
+# Validator
 
-_Wisest of the centaurs, teacher of heroes._
+_Code review and quality assurance agent._
 
 Your personal scratchpad. Use this for:
 

package/dist/templates/.openfleet/{experience → private/experience}/README.md

@@ -8,8 +8,7 @@ Self-healing systems with long-term memory. Learned knowledge from past work.
 experience/
 ├── runbooks/              # How-to guides for recurring tasks
 ├── troubleshooting/       # Problem → solution mappings
-├── lessons/               # Insights and best practices
-└── blunders/              # Mistakes to avoid
+└── lessons/               # Insights, best practices, and mistakes to avoid
 ```
 
 ## Usage

package/dist/templates/.openfleet/private/preferences.md

@@ -0,0 +1,113 @@
+# User Preferences
+
+Read this before starting any implementation task.
+
+## Docstrings
+
+- One-liner starts right after the opening `"""`
+- Numbered bullet list of what the function does (if non-trivial)
+- Optional `Example:` block for non-obvious usage
+- No `Args` or `Returns` sections
+- Add a blank line between the docstring and the code body
+- Single-line docstring is fine for simple functions — don't overcomplicate
+- No file-level docstrings
+- No private function docstrings
+
+## Comments
+
+Code should be self-documenting. Avoid comments unless there is a genuine gotcha or
+non-obvious complexity.
+
+## Logging
+
+**Use `logger.span()` for:**
+
+- All database operations
+- External API calls
+- Business logic boundaries
+- Any operation where timing/duration matters
+
+**Use `logger.info()` for:**
+
+- State-changing operations (create, update, delete) — audit trail
+- Operation outcomes (success/failure messages)
+- NOT for read operations (spans are sufficient)
+
+**Span naming** — follow OpenTelemetry dot notation: `entity.action`
+
+## Failing tests
+
+If a test fails, do not simply rerun it with an increased timeout. Unless you have concrete
+logs-based evidence that the failure is purely a timing issue, bumping the timeout is just
+noise — the underlying problem will resurface.
+
+Instead:
+
+- **Read the logs.** What actually failed and why?
+- **Check other metrics.** Is a dependency down? Is there a race condition? Did an assertion fail on wrong data?
+- **Understand before acting.** A test that passes with a higher timeout is not a fixed test.
+
+## Optional fields
+
+Be deliberate about whether a field is truly optional. Loosely marking fields as optional
+(`T | undefined`, `T | None`, `?: T`) forces every caller to add `if x` guards throughout
+the codebase, spreading defensive boilerplate everywhere.
+
+Before making a field optional, ask:
+
+- **Is this field ever genuinely absent?** If it always exists after construction, make it required.
+- **Are you making it optional just to avoid passing it at the call site?** That's the wrong fix — rework the constructor or factory instead.
+
+```ts
+// ❌ Loose — now every caller has to guard
+interface Session {
+  id: string
+  agentName?: string  // is this ever really missing?
+}
+if (session.agentName) { ... }
+
+// ✅ Tight — guaranteed present, no guards needed
+interface Session {
+  id: string
+  agentName: string
+}
+```
+
+Optional should mean **genuinely absent in valid states**, not **"I wasn't sure so I added a `?`"**.
+
+## Code style
+
+**Prefer Pydantic `BaseModel` over `dataclass`**
+Pydantic gives you validation, serialization, and IDE support for free. Only reach for `dataclass` if you have a specific reason to avoid Pydantic.
+
+**Prefer dependency injection over module-level instantiation**
+Instantiating objects at the module level makes code hard to test and creates hidden coupling. Pass dependencies explicitly so they can be swapped, mocked, or configured at the call site.
+
+```py
+# ❌ Module-level — hidden, untestable
+db = Database()
+
+def get_user(id: str):
+    return db.find(id)
+
+# ✅ Injected via dependencies.py
+# dependencies.py
+def get_db() -> Database:
+    return Database(settings.DATABASE_URL)
+
+# router.py
+@router.get("/users/{id}")
+def get_user(id: str, db: Database = Depends(get_db)):
+    return db.find(id)
+```
+
+**Prefer extracting logic into hooks over long components**
+When a component grows complex, resist the urge to keep adding to it. Pull state and side-effect logic into a dedicated hook so the component stays focused on rendering.
+
+## Function placement
+
+When adding new methods or functions, place them thoughtfully:
+
+- Public before private
+- By importance: `start`, `run`, `process` near top; helpers near bottom
+- Don't blindly append to the end of a file

package/dist/templates/.openfleet/public/standards/code-style.md

@@ -0,0 +1,11 @@
+# Code Style Standards
+
+## Type definitions
+
+Before defining a new type, always check:
+
+1. **Does it already exist?** Search the codebase before creating a duplicate.
+2. **Can it be imported from a 3rd-party library?** Prefer importing from the library
+   that owns the concept over redefining it locally.
+
+Only define a new type if it genuinely doesn't exist anywhere reachable.

package/dist/utils/directory-init.d.ts

@@ -1 +1,2 @@
 export declare function initializeDirectories(): void;
+export declare function checkMigrationNeeded(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openfleet",
-  "version": "0.3.15",
+  "version": "0.4.0",
   "description": "SPARR framework agents + infinite context for OpenCode",
   "type": "module",
   "main": "./dist/index.js",

package/dist/agents/read-only.d.ts

@@ -1,2 +0,0 @@
-import type { AgentConfig } from "@opencode-ai/sdk";
-export declare const readonlyOrchestratorAgent: AgentConfig;

package/dist/agents/scout.d.ts

@@ -1,2 +0,0 @@
-import type { AgentConfig } from "@opencode-ai/sdk";
-export declare const scoutAgent: AgentConfig;

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

@@ -1,6 +0,0 @@
-# Blunders
-
-Mistakes to avoid. Learning from failure.
-
-This is not a blame log. It's a learning resource.
-Recording blunders helps prevent repeating them.

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

@@ -1,15 +0,0 @@
-# Reviews
-
-Human review artifacts and feedback.
-
-## Structure
-
-```
-reviews/
-├── README.md                    # This file
-└── YYYY-MM-DD_<topic>.md        # Individual review records
-```
-
-## Usage
-
-Store feedback from human reviews here for future reference.

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

@@ -1,16 +0,0 @@
-# Sessions Directory
-
-Conversation records organized by date.
-
-## Structure
-
-```
-sessions/
-└── YYYY-MM-DD/
-    └── NNN_topic-slug.md
-```
-
-## Usage
-
-Sessions are auto-generated by the `save_conversation` tool.
-Each session captures a complete conversation with metadata.

package/dist/templates/.openfleet/standards/code-style.md

@@ -1,3 +0,0 @@
-# Code Style Standards
-
-_To be customized for your project._

package/dist/tools/save-conversation/counter.d.ts

@@ -1,31 +0,0 @@
-/**
- * Gets the next counter for a given date.
- *
- * This function:
- * 1. looks inside the date subdirectory (sessions/YYYY-MM-DD/)
- * 2. extracts all counters from files matching NNN_slug.md pattern
- * 3. finds the highest counter
- * 4. returns next counter (highest + 1), zero-padded to 3 digits
- *
- * Example:
- *   >>> const counter = await getNextCounter("2025-12-23");
- *   >>> counter
- *   '003'
- */
-export declare function getNextCounter(date: string): Promise<string>;
-/**
- * Gets current date in YYYY-MM-DD format (UTC).
- */
-export declare function getCurrentDate(): string;
-/**
- * Validates date format (YYYY-MM-DD).
- */
-export declare function isValidDateFormat(date: string): boolean;
-/**
- * Gets all session files for a specific date.
- */
-export declare function getSessionsForDate(date: string): string[];
-/**
- * Builds filename from counter and slug (NNN_slug.md format).
- */
-export declare function buildFilename(counter: string, slug: string): string;

package/dist/tools/save-conversation/session-writer.d.ts

@@ -1,17 +0,0 @@
-import type { SessionEntry } from "./types";
-/**
- * Writes a session entry to the sessions directory.
- *
- * This function:
- * 1. ensures date subdirectory exists (sessions/YYYY-MM-DD/)
- * 2. builds filename from counter and slug (NNN_slug.md)
- * 3. generates enhanced session content
- * 4. writes file atomically
- * 5. returns full file path
- */
-export declare function writeSession(entry: SessionEntry): string;
-/**
- * Calculates session duration from timestamp metadata.
- * Returns formatted string like "45 minutes" or "2 hours 15 minutes".
- */
-export declare function calculateDuration(startTime: Date, endTime: Date): string;

package/dist/tools/save-conversation/slug-generator.d.ts

@@ -1,14 +0,0 @@
-import type { SlugContext } from "./types";
-/**
- * Generates a semantic slug using simple context string.
- *
- * This function takes a context string (usually from user's note or session summary)
- * and generates a kebab-case slug using Claude Haiku.
- *
- * Example:
- *   >>> const slug = await generateSlug("Implemented user authentication system");
- *   >>> slug
- *   'implement-user-auth'
- */
-export declare function generateSlug(contextString: string, context?: SlugContext): Promise<string>;
-export declare function slugToTitle(slug: string): string;

package/dist/tools/save-conversation/types.d.ts

@@ -1,28 +0,0 @@
-export interface SaveConversationArgs {
-    note?: string;
-}
-export interface SessionEntry {
-    sessionID: string;
-    transcriptPath: string;
-    savedAt: string;
-    date: string;
-    counter: string;
-    slug: string;
-    title: string;
-    summary: string;
-    note?: string;
-    duration?: string;
-    messageCount: number;
-    tokensBefore: number;
-    tokensInput?: number;
-    tokensOutput?: number;
-}
-export interface SlugContext {
-    maxMessages?: number;
-    maxContextChars?: number;
-}
-export interface CounterInfo {
-    date: string;
-    counter: string;
-    highestFound: number;
-}