@hybridlabor-api/aos 4.6.6 → 4.7.0

package/skills/basic/godmode-ui-ux/references/anti-slop-rules.md

@@ -1,64 +1,68 @@
-# Anti-Slop Directive & AI Tells Reference
+# Anti-Slop Directive & Craftsmanship Gate
 
-This authoritative reference details all forbidden patterns, AI clichés, and layout mistakes strictly prohibited in BDB frontend designs.
+This authoritative reference details all forbidden patterns, AI clichés, and layout defects prohibited in frontend designs under `godmode-ui-ux`.
 
-## Brand Discovery Context Rules
-- **Brand Defined**: Color bans (Lila Ban, default blue/purple gradient bans) and font bans (Inter ban) are **SUSPENDED**.
-- **No Brand Defined**: ALL bans below (including color and font bans) are **ACTIVE**.
-- **Pattern Bans**: Layout, content, component, and interaction anti-slop rules are **ALWAYS ACTIVE** regardless of brand.
+---
+
+## 🧭 Brand Discovery Precedence Rules (STRICT HIERARCHY)
+- **Brand Defined in `DESIGN.md`:** Color bans (Lila/Purple ban) and font bans (Inter ban) are **SUSPENDED**. Project-specific CI colors and typography take absolute precedence.
+- **No Brand Defined:** ALL bans below (including color and font defaults) are **ACTIVE**.
+- **Structural Anti-Slop:** Component, layout, mobile ergonomic, and copywriting anti-slop rules are **ALWAYS ACTIVE** regardless of brand.
 
 ---
 
 ## 1. Visual & CSS Tells
 
-- [ ] **NO Neon or Outer Glows**: Do not use default high-radius `box-shadow` glows or auto-glows. Use inner borders (`border-white/10`) or subtle, background-tinted diffuse shadows.
-- [ ] **NO Pure Black**: Never use `#000000`. Use Off-Black, Zinc-950, or Charcoal (`oklch(0.20 0.01 285)`).
-- [ ] **NO Oversaturated Accents**: Desaturate accents to blend elegantly with neutrals (saturation < 80%).
-- [ ] **NO Lila / AI Purple-Blue Aesthetic (Lila Ban)**: *(Active only when no brand is defined)* The generic purple/blue SaaS gradient background aesthetic is strictly BANNED. No neon purple button glows, no default mesh backgrounds. Use neutral bases (Zinc/Slate) with high-contrast singular accents (Emerald, Electric Blue, Deep Rose).
-- [ ] **NO Excessive Gradient Text**: Do not use text-fill gradients for large section headers or titles.
-- [ ] **NO Custom Mouse Cursors**: Custom cursor overlays break accessibility, lag on mobile, and degrade performance.
-- [ ] **NO Flat Design Without Hierarchy**: Flat design is not an excuse for missing visual hierarchy. Use multi-layered diffuse shadows tinted to background hues.
-- [ ] **NO Arbitrary Z-Index Spam**: Do not spam `z-50` or `z-10`. Use z-index exclusively for systemic layer contexts (navbars, modals, toasts, tooltips).
+- [ ] **NO Neon or Outer Glows:** Never use default high-radius outer `box-shadow` halos. Use 1px inner borders (`border-white/10`) or subtle, background-tinted diffuse shadows.
+- [ ] **NO Pure Black:** Never use `#000000`. Use Off-Black, Zinc-950, or Charcoal (`oklch(0.20 0.01 285)`).
+- [ ] **NO Oversaturated Accents:** Desaturate accents to blend cleanly with neutrals (saturation < 80%).
+- [ ] **NO AI Purple-Blue Default Mesh (Lila Ban):** *(Suspended when brand is defined)* Generic purple/blue SaaS gradient backgrounds are strictly BANNED as defaults. Use neutral bases (Zinc/Slate) with high-contrast singular accents.
+- [ ] **NO Gradient Text for Body or Subheadings:** Text-fill gradients are banned for standard copy; reserve subtle shifts for hero accent words only.
+- [ ] **NO Custom Mouse Cursors:** Custom cursor overlays break accessibility, lag on touch devices, and degrade performance.
+- [ ] **NO Flat Design Without Depth:** Flat design requires visual hierarchy. Use multi-layered diffuse shadows or distinct tonal contrast.
+- [ ] **NO Arbitrary Z-Index Spam:** Do not spam `z-50` or `z-10`. Use z-index exclusively for systemic layer contexts (navbars, modals, toasts, tooltips).
 
 ---
 
 ## 2. Typography Tells
 
-- [ ] **NO Inter Font Default**: *(Active only when no brand is defined)* Inter as a default font is BANNED. Force unique character using `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
-- [ ] **NO System Font Laziness**: Avoid unstyled system fonts (Arial, Roboto, standard system-ui) without explicit design intent.
-- [ ] **NO Serif Fonts on Dashboards**: Serif fonts are strictly BANNED for Dashboard/B2B Software UIs. For these contexts, use exclusively high-end Sans-Serif + Mono pairings (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`). Use Serif strictly for editorial or creative projects.
-- [ ] **NO Oversized H1s**: The primary heading should not scream. Control hierarchy with weight, tracking (`tracking-tighter`), and color contrast, not just massive scale.
+- [ ] **NO Inter Font Default:** *(Suspended when brand is defined)* Inter as an unthinking default is BANNED. Select distinct typefaces: `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
+- [ ] **NO System Font Laziness:** Avoid unstyled system fonts (Arial, Roboto, standard system-ui) without explicit design intent.
+- [ ] **NO Serif Fonts on B2B Dashboards:** Serif fonts are BANNED for dense data dashboards. Use high-performance Sans + Mono pairings (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`).
+- [ ] **NO Oversized H1s:** Primary headings must establish hierarchy with weight, tracking (`tracking-tighter`), and contrast, rather than overwhelming scale.
 
 ---
 
-## 3. Layout & Structure Tells
+## 3. Layout & Mobile Ergonomics (R-03 / Craftsmanship)
 
-- [ ] **NO Default Sidebar/Header Dashboards**: Do not build standard sidebar/header layouts if the feature is better served as a modal, command palette, or single-column focused view.
-- [ ] **NO Centered Hero Sections (when Variance > 4)**: Centered Hero/H1 sections are strictly BANNED when `DESIGN_VARIANCE > 4`. Use split screen (50/50), left-aligned content with right-aligned asset, or asymmetric whitespace.
-- [ ] **NO 3-Column Equal Card Layouts**: The generic "3 equal cards horizontally" feature row is BANNED. Use a 2-column zig-zag, asymmetric grid (e.g. 70/30), or horizontal scrolling approach instead.
-- [ ] **NO Arbitrary Border-Radius Mixing**: Do not mix `rounded-md` and `rounded-2xl` randomly. Follow the mathematical token scale (`sm: 6px`, `md: 12px`, `lg: 16px`, `xl: 24px`, `2xl: 40px`, `full: 9999px`).
-- [ ] **NO Card Overuse in High Density**: For `VISUAL_DENSITY > 7`, generic card containers are strictly BANNED. Use logical grouping via `border-t`, `divide-y`, or purely negative space.
-- [ ] **NO Viewport Instability (`h-screen`)**: NEVER use `h-screen` for full-height hero sections. ALWAYS use `min-h-[100dvh]` to prevent layout jumping on mobile browsers (iOS Safari).
-- [ ] **NO Fragile Flex-Math**: NEVER use complex flexbox percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`).
+- [ ] **NO Default Sidebar/Header Dashboards:** Do not build cookie-cutter sidebar layouts if the feature is better served as a command palette, focused panel, or single-column flow.
+- [ ] **NO Centered Hero Sections (when Variance > 4):** Centered Hero/H1 sections are BANNED when `DESIGN_VARIANCE > 4`. Use asymmetric splits (60/40), left-aligned type with right-aligned visual assets, or disciplined whitespace.
+- [ ] **NO 3-Column Equal Card Layouts:** The generic "3 equal cards horizontally" feature row is BANNED. Use bento grids, 2-column zig-zag, or asymmetric horizontal flows.
+- [ ] **NO Arbitrary Border-Radius Mixing:** Adhere strictly to the mathematical token scale (`sm: 6px`, `md: 12px`, `lg: 16px`, `xl: 24px`, `2xl: 40px`, `full: 9999px`).
+- [ ] **NO Card Overuse in High Density:** For `VISUAL_DENSITY > 7`, generic card wrappers are BANNED. Group content via structural dividers (`divide-y`, `border-t`) or pure whitespace.
+- [ ] **NO Viewport Instability (`h-screen`):** NEVER use `h-screen` for full-height sections. ALWAYS use `min-h-[100dvh]` to prevent viewport jumping on mobile browsers (iOS Safari).
+- [ ] **NO Sub-44px Touch Targets:** On touch devices, every button, link, and interactive icon must have a minimum interactive hit area of `44x44px` (`min-h-[44px] min-w-[44px]`).
+- [ ] **NO Fragile Flex-Math:** NEVER use fragile percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`).
 
 ---
 
-## 4. Content, Copywriting & Data Tells (The "Jane Doe" Effect)
+## 4. Copywriting & Content Integrity (R-02 / No AI Fluff)
 
-- [ ] **NO Generic Names**: "John Doe", "Jane Doe", "Sarah Chan", and "Jack Su" are BANNED. Use realistic, contextual names.
-- [ ] **NO Startup Slop Brand Names**: "Acme", "Nexus", "SmartFlow", "TechCorp". Invent premium, contextually relevant brand names.
-- [ ] **NO AI Copywriting Clichés**: Banned words: "Elevate", "Seamless", "Unleash", "Next-Gen", "Tailored", "Empower", "Revolutionize", "Frictionless". Use direct, concrete action verbs.
-- [ ] **NO Fake / Predictable Numbers**: Avoid predictable demo values like `99.99%`, `50%`, or basic phone numbers (`1234567`). Use organic, messy data (`47.2%`, `+1 (312) 847-1928`).
-- [ ] **NO Emoji Icons [CRITICAL]**: NEVER use emojis in code, markup, text content, or alt text. Replace all symbols with Phosphor, Radix, or Lucide SVG icons.
+- [ ] **NO AI Copywriting Clichés:** The following buzzwords are strictly BANNED:
+  *"Elevate", "Seamless", "Unleash", "Next-Gen", "Tailored", "Empower", "Revolutionize", "Frictionless", "Supercharge", "Game-changer".*
+  Write plain, clear, concrete, human language.
+- [ ] **NO Generic Placeholder Personas:** "John Doe", "Jane Doe", "Sarah Chan", and "Jack Su" are BANNED. Use realistic, domain-specific names.
+- [ ] **NO Cliché Startup Names:** "Acme", "Nexus", "SmartFlow", "TechCorp". Use authentic, contextual brand naming.
+- [ ] **NO Fake Statistics:** "99.9% customer satisfaction", "Loved by 10,000+ teams" without real context or evidence are BANNED.
 
 ---
 
-## 5. External Resources & Component Tells
+## 5. UI Completeness & Accessibility (R-25, R-27, R-32)
 
-- [ ] **NO Broken Unsplash Links**: Do not use raw Unsplash URLs. Use absolute, reliable placeholders (`https://picsum.photos/seed/{string}/800/600`) or SVG UI Avatars.
-- [ ] **NO Uncustomized shadcn/ui**: You may use `shadcn/ui`, but NEVER in its generic default state. You MUST customize radii, colors, and shadows to match project tokens.
-- [ ] **NO Missing Interactive Lifecycle States**: Every interactive component must provide:
-  - **Loading State**: Skeletal loaders matching component dimensions (avoid generic circular spinners).
-  - **Empty State**: Purposeful, helpful empty state indicating how to populate data.
-  - **Error State**: Inline form/data error reporting with recovery paths.
-  - **Tactile Feedback**: On `:active`, apply physical push simulation (`scale-[0.98]` or `-translate-y-[1px]`).
+- [ ] **Full UI State Handling:** Every data component must explicitly implement:
+  1. **Loading State:** Skeleton loader (not generic spinning wheels).
+  2. **Empty State:** Helpful zero-data message with a clear call-to-action.
+  3. **Error State:** Human-readable error message with recovery/retry option.
+  4. **Success State:** Clear feedback upon action completion.
+- [ ] **Contrast Compliance:** Text must satisfy WCAG AA contrast (minimum `4.5:1` for normal body text, `3:1` for large text).
+- [ ] **Keyboard Accessibility:** Every interactive element must display visible, accessible focus indicators (`focus-visible:ring-2 focus-visible:ring-offset-2`).

package/skills/basic/godmode-ui-ux/references/taste-archetypes.md

@@ -0,0 +1,49 @@
+# Aesthetic Taste Archetypes Reference
+
+Sourced from `taste-skill` and integrated into AOS `godmode-ui-ux`.
+When Phase 0 Brand Discovery indicates no pre-existing client CI, the engineer or agent selects ONE of these archetypes rather than generating generic, uninspired AI layouts.
+
+---
+
+## 1. Utilitarian Minimalist & Editorial
+**Best for:** Dev tools, documentation, knowledge bases, modern SaaS platforms, editorial publications.
+
+- **Palette:** High-contrast warm monochrome. Off-white/cream backgrounds in light mode (`#fcfbf9`), charcoal/zinc in dark mode (`#121214`). Accents are muted pastels or single sharp contrast tones.
+- **Typography:** Extreme typographic scale contrast. Heavy grotesque or geometric display headlines paired with disciplined, readable body copy (`Geist`, `Cabinet Grotesk`, `Satoshi`).
+- **Layout:** Bento grids with deliberate asymmetric whitespace. Content-first hierarchy where type and negative space structure the page instead of visual noise.
+- **Details:** Hairline 1px structural dividers (`border-zinc-200 dark:border-zinc-800`), flat cards without heavy drop-shadows, zero gradient text.
+
+---
+
+## 2. Industrial Brutalist & Tactical Telemetry
+**Best for:** Analytics dashboards, developer consoles, hardware monitors, command-and-control interfaces.
+
+- **Palette:** Deep dark telemetry (`#090a0f`) or Swiss industrial print off-white (`#f4f4f0`). Monochromatic substrate with high-alert accenting (International Klein Blue, Signal Amber, or Crimson Red).
+- **Typography:** Heavy sans-serif display headers paired with monospaced data tables (`JetBrains Mono`, `Geist Mono`). Numbers and status indicators are oversized.
+- **Layout:** Strict modular grids with visible gridlines (`divide-x divide-y`). High information density, metadata timestamps, technical framing brackets `[+]`, coordinate tags.
+- **Details:** Crisp borders, zero rounded pill corners (`rounded-none` or `rounded-sm`), analog precision, functional status badges.
+
+---
+
+## 3. High-End Tactile / Soft Luxury
+**Best for:** FinTech, consumer products, luxury e-commerce, portfolio showcases, premium creative tools.
+
+- **Palette:** Deep OLED black / dark zinc (`#09090b`), soft muted surface elevations (`#141417`, `#1c1c21`). Warm neutral highlights.
+- **Typography:** Refined, elegant sans-serif or modern editorial serifs for titles (`PP Editorial New`, `Outfit`, `Plus Jakarta Sans`). Tight tracking on headings (`tracking-tight`).
+- **Layout:** Generous breathing room, floating detached navigation bars with subtle backdrop blur, asymmetric card sizing (e.g. 60/40 splits).
+- **Details:** Ultra-diffuse layered shadows (`box-shadow: 0 20px 40px -15px rgba(0,0,0,0.5)`), 1px subtle top-border highlights (`border-t border-white/10`), haptic feedback on interactive elements.
+
+---
+
+## 4. Ethereal Clean Modern
+**Best for:** AI applications, productivity suites, modern collaborative workspaces.
+
+- **Palette:** Neutral slate/zinc foundation. Single high-energy accent token defined in OKLCH (`oklch(0.65 0.22 260)`).
+- **Typography:** Clean geometric Grotesk with high legibility.
+- **Layout:** Fluid responsive bento grid with dynamic card hierarchy, clear primary focal point.
+- **Details:** Micro-interactions on hover, refined 12px/16px rounded corners, crisp accessibility-verified contrast ratios (> 4.5:1 for body text).
+
+---
+
+## 🔒 Enforcement Rule
+Pick **ONE** archetype per project during Phase 0 Brand Discovery. Do not mix disparate styles within the same interface.

package/skills/basic/startcycle/SKILL.md

@@ -60,6 +60,9 @@ A straight-line run through the BDB agent roster. Whoever invokes this skill inv
 - **Reads**: the goal (or `/bdbrainstorm` / `/grill-me` output), existing architecture.
 - **Action**: turns the goal into a system plan with an explicit capability map — module boundaries, dependency direction, what streams the goal actually touches.
 - **Writes**: `production_artifacts/00_execution_plan.md`
+- The plan uses the agenttrail component convention: `## Name {#id}` components with optional `needs:` / `files:` lines, and tasks as `- [ ] ... {#id}`.
+- The Architect renders the architecture with `aos-archify` to `production_artifacts/00_architecture.html` and links it from the relevant component with a `url:` line.
+- Plan-canvas can review that HTML too.
 
 ### 2. TechLead
 - **Agent**: `techlead`
@@ -70,6 +73,9 @@ A straight-line run through the BDB agent roster. Whoever invokes this skill inv
 > **Optional — Plan Canvas.** Before or alongside TechLead's gate, the plan can be reviewed in the browser: `aos-plan-canvas open production_artifacts/00_execution_plan.md`, then `aos-plan-canvas await …`. An `approve` verdict is a human confirmation of the gate. This is optional; the pipeline runs unchanged without it. See the `plan-canvas` skill.
 
 ### 3. Build (parallel, stream-selective)
+
+**Trigger B — start the live map:** `aos-trail . --plan production_artifacts/00_execution_plan.md --no-open` (safe to run twice: it reuses a map already running for this repo). Inside AO (env var `AO_BROWSER_CAPABILITY` set) also run `ao preview <url>`. Tell each build agent to mark its tasks `[~]` before starting work, `[x]` when done, `[!]` when stuck, with an indented `by: <agent>` line, saving the plan file immediately after each change. See the `agenttrail` skill.
+
 Run only the streams the goal actually needs. A plain backend feature does not need step 3a or 3c; a pure copy change does not need 3b. Each stream's `skills:` frontmatter already lists what it should reach for — the invoker passes that list through rather than restating it here.
 
 | Stream | Agent | Reads | Writes |
@@ -110,6 +116,7 @@ Run only the streams the goal actually needs. A plain backend feature does not n
   3. valid trade-off (advisory)
   4. noise
 - **Writes**: `production_artifacts/review_findings.md`
+- **Optional — architecture delta**: compare planned vs built architecture with `aos-archify` (see the `archify` skill, architecture delta).
 
 **The linear pipeline ends here by default.** A plain build or refactor goal is done at step 4 — it does not automatically drag a quality gate and release report behind it.
 

package/skills/basic/startcycle-graph/SKILL.md

@@ -106,6 +106,18 @@ the model followed it "in spirit" inline instead of invoking the script —
 silently skipping the whole graph, with no `state.json`, no subagents, no
 Reviewer, and no quality gate ever running).
 
+## Live map
+
+When the build phase begins, the dispatcher starts the aos-trail live map
+(Trigger B) with the command below; it is safe to run twice, since
+`aos-trail` reuses a map already running for this repo:
+`aos-trail . --plan production_artifacts/00_execution_plan.md --no-open`
+(it prints a URL, default http://localhost:5330; inside AO, where
+`AO_BROWSER_CAPABILITY` is set, also run `ao preview <url>`). Agents follow
+the status-mark rules from the `agenttrail` skill: `[~]` before starting,
+`[x]` when done, `[!]` when stuck, with `by: <agent>`, saving the plan file
+immediately.
+
 ## Why this file is a thin router, not a spec
 
 The full contract — state schema, node/edge table, the Stop-hook

package/skills/basic/startcycle-graph-user/SKILL.md

@@ -138,6 +138,9 @@ that silently inherits that is the exact waste this tiering exists to avoid.
 - Report the outcome directly to the user. Nothing gets written to
   `.agents/`, no `state.json`, no persistent contract — this graph existed for
   the duration of the task and is gone once it's done.
+- Optionally run `aos-trail . --no-open` (no `--plan`, because this variant
+  writes no plan file) to watch the workers' file activity live in the
+  browser; see the `agenttrail` skill.
 
 ## 5. When to reach for `/startcycle-graph` instead
 

package/skills/basic/teamwork-preview/SKILL.md

@@ -195,6 +195,8 @@ Seek explicit approval from the user before triggering execution.
 
 Once approved by the user:
 
+Before delegating, start the live map (Trigger B) so the user can follow the team: `aos-trail . --no-open` (or with `--plan <plan-file>` if one exists) (safe to run twice: it reuses a map already running for this repo). Inside AO (env var `AO_BROWSER_CAPABILITY` set) also run `ao preview <url>`. See the `agenttrail` skill.
+
 ### 1. In Antigravity Harness
 If running in Google Antigravity with native subagent support:
 - Call `invoke_subagent`:

package/skills/bdbrainstorm/SKILL.md

@@ -37,6 +37,7 @@ You are strictly required to enforce the following 6 pillars in your process:
 ### 6. Shipping Godmode & Pipeline Hand-off
 - Before the brainstorm concludes, verify that the plan satisfies the `godmode-shipping` rules (Spec-Driven Development, feature flags, rollback strategies).
 - **Mandatory — Plan Canvas review.** Write the aligned plan to a file, then run `aos-plan-canvas open <file>` followed by `aos-plan-canvas await <file>` and leave it running. The user reviews and annotates in the browser (Mermaid diagrams render live, click-to-annotate, chat rail); do not write `state.goal` or hand off to `/startcycle-graph` before an `approve` verdict comes back. A `request_changes` verdict means revise the plan file and reopen the session — it live-reloads. This runs identically regardless of which agent harness is executing this skill; it is a plain CLI, not a Claude-Code-specific mechanism. See the `plan-canvas` skill.
+- Write the plan in the agenttrail component convention (`## Name {#id}` components with `needs:` / `files:` lines, tasks as `- [ ] ... {#id}`) and render the architecture with `aos-archify` so the canvas review includes the diagram; after the `approve` verdict, Trigger A starts the live map. See the `agenttrail` and `archify` skills.
 - Present the aligned plan and hand off to `/startcycle-graph` for execution — write `state.goal` from this session's output and let `/startcycle-graph`'s dispatcher take it from there (see `.agents/graph.md`). This skill does not invoke `/startcycle-graph`'s agents itself; it produces the goal they read.
 
 ## Execution Rules

package/skills/global_config/agenttrail/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kelly Sun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/global_config/agenttrail/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: agenttrail
+description: Live map of a multi-agent build in the browser: which plan component is being worked on, by which agent or harness, what is done and what is stuck. Use when a multi-agent pipeline starts (/startcycle, /startcycle-graph, /teamwork-preview) or after a plan-canvas approve, or when the user asks to see what the agents are doing.
+category: bdb-core
+metadata:
+  version: "0.2.0"
+  origin: sodiumsun/agenttrail@e4ba2da
+  license: MIT
+---
+
+<!-- Source: sodiumsun/agenttrail bin/agenttrail.mjs + public/index.html — MIT, see THIRD_PARTY_NOTICES.md -->
+
+# agenttrail — live pipeline map
+
+agenttrail serves a browser board that mirrors a multi-agent build in real time: which plan component is being worked on, by which agent or harness, what is done and what is stuck. It observes only — it never runs agents and never marks tasks done.
+
+## Start the map
+
+```bash
+aos-trail . --plan production_artifacts/00_execution_plan.md --no-open
+```
+
+It prints the URL (default http://localhost:5330, next free port if taken). Open that URL for the user. If running inside AO (env var `AO_BROWSER_CAPABILITY` is set), run `ao preview <url>` so it shows in AO's Browser tab. Without a plan file, start it with just `aos-trail .` — it then shows file activity only.
+
+## Plan convention
+
+The plan file uses components and tasks:
+
+- `## Plain-language name {#id}` = a component (5-9 per plan), stable ids
+- under it optional lines: `needs: [id, id]`, `links: [id]`, `files: [src/**]`, `url: production_artifacts/00_architecture.html`
+- tasks: `- [ ] Outcome {#task-id}`; mark `[~]` BEFORE starting, `[x]` when done, `[!]` when stuck, and add an indented `by: <agent>` line (claude, codex, agy, opencode)
+- save the file immediately after each status change; never batch updates to the end
+- Mermaid blocks and prose may stay in the file; the map ignores them.
+
+## Live agent events
+
+The AOS installer registers `.claude/hooks/trail-relay.mjs --agent <harness>` for Claude Code (PreToolUse, PostToolUse, SessionStart, Stop, SubagentStop), Antigravity and Codex (PreToolUse, Stop). The OpenCode plugin and mcsc (for the CLI workers it delegates to) post events directly. Events are fire-and-forget (300 ms cap) and never block a tool call; with no map running they are dropped.
+
+A component's `url:` may be a path under `production_artifacts/` — the map serves that folder, so e.g. `url: production_artifacts/00_architecture.html` opens the archify diagram from the card.
+
+## Stop
+
+The daemon runs until its terminal/process ends; `aos-trail up` relaunches saved boards.
+
+## Rules
+
+- Never create a root `PLAN.md` in a user repo during an AOS pipeline — always point at the pipeline's plan with `--plan`.
+- Never mark `[x]` without evidence in the code.