Repository Structure

vivera/
├── README.md                                    # Documentation & architecture flow
├── LICENSE                                      # MIT License
├── package.json                                 # npm scripts & devDependencies (@mermaid-js/mermaid-cli)
├── Super Ultra Code Plan Implementation.md      # Orchestrator skill: gates, classification, phase router
├── MEMORY.md                                    # Distilled in-repo rules from Step 6 learning harvest
├── install.sh                                   # 1-command installer: skills for every detected harness, sprite agents for six
├── install.ps1                                  # Windows installer: copy mode, skills only (run under pwsh 7.6.6 on Linux; not verified on Windows)
├── Dockerfile                                   # Container image on oven/bun:1.4.2-debian, non-root user, standard tier (never built)
├── .dockerignore                                # Keeps private state out of the image
├── .gitattributes                               # Forces LF for *.sh, .githooks/* and scripts/install/tiers.tsv (a CRLF checkout breaks the installer)
├── .devcontainer/
│   └── devcontainer.json                        # Builds the Dockerfile base stage and links the mounted workspace
├── mermaid.config.json                          # Light theme: palette + embedded-font stack
├── mermaid.dark.config.json                     # Dark variant, same layout and font
├── puppeteer-config.json                        # Headless flags for mermaid-cli rendering
├── .claude/
│   ├── agents/                                  # Seven Harvest Sprite subagents, generated from agents/roles
│   └── hooks/
│       └── block-git-writes.mjs                 # PreToolUse guard: subagents never write git state
├── agents/
│   ├── roles/                                   # Four role templates: researcher, implementer, debugger, reviewer
│   └── crew.json                                # Assigns each Harvest Sprite a role and a color
├── .githooks/
│   └── pre-commit                               # Non-blocking: refresh graphify graph when a commit includes Markdown
├── .github/
│   └── workflows/
│       ├── ci.yml                               # CI: bun install, render, drift gate, validate, test
│       └── release.yml                          # Release: dispatch only, dry_run defaults to true, publishes only on request
├── diagrams/                                    # Generated SVGs (only the hero pair is committed)
│   ├── lifecycle.svg                            # README hero, light
│   └── lifecycle-dark.svg                       # README hero, dark
├── docs/
│   ├── diagrams-src/
│   │   └── lifecycle.mmd                        # Mermaid source of the README hero diagram
│   ├── images/
│   │   ├── vivera.jpg                           # README mascot artwork
│   │   ├── btn-harvest-sprites.jpg              # Back to Nature (PS1) Harvest Sprites illustration
│   │   └── sprites/                             # Seven Harvest Sprite portraits (chef.png ... bold.png)
│   ├── graphify-integration.md                  # graphify setup, memory bounds, and runbook
│   ├── graphify-indexed-session-artifacts.md    # One session's review report and ledger, kept visible to graphify query
│   ├── graphify-indexed-install-methods.md      # The install-methods session: lock, plan, findings, kept visible to graphify query
│   └── code-plan/
│       ├── <date>-<slug>.manifest.md            # Batch manifests written before dispatch
│       ├── plans/
│       │   └── <date>-<slug>.md                 # ultra-plan/v1 plans this repo executed
│       └── spikes/                              # Spike reports & hypothesis evaluation
├── examples/
│   ├── worked-example.md                        # Full pipeline walkthrough (filled-in reference)
│   ├── deep-research-worked-example.md          # Citation-grounded report at target density
│   ├── graph-viewer-demo.html                   # Self-contained knowledge-graph viewer demo (synthetic data)
│   └── graph-viewer-demo.md                     # What the demo shows and how it is generated
├── scripts/
│   ├── sync.sh                                  # Bidirectional sync (~/.config/ai <-> repo)
│   ├── render-diagrams.sh                       # Render all mermaid blocks to SVG
│   ├── validate-skill.mjs                       # Frontmatter, link, token, mermaid & a11y lint
│   ├── check-runner-contract.mjs                # Fast structural check for runner frontmatter keys
│   ├── check-duplicate-defs.mjs                 # Diff-scoped gate: a definition a branch adds whose name already exists elsewhere
│   ├── check-duplicate-defs.test.mjs            # Languages, skips, waiver, exit codes, and the calibration rules
│   ├── validate-agents.mjs                      # Lint .claude/agents frontmatter (Claude Code ignores bad fields silently)
│   ├── validate-agents.test.mjs                 # Field, name, skills, and CLI exit-code tests
│   ├── gen-sprite-agents.mjs                    # Render the sprite crew for six harnesses (CLI over scripts/sprite-agents/)
│   ├── gen-sprite-agents.test.mjs               # CLI, hook pinning, drift, and hand-written-file guards
│   ├── sprite-agents/                           # Renderers behind gen-sprite-agents.mjs, one file per harness
│   │   ├── crew.mjs                             # Roster (agents/crew.json), template frontmatter, hook scripts
│   │   ├── sync.mjs                             # Write, check and clean the generated files (marker line)
│   │   ├── guard.mjs                            # Prose git guard for harnesses without a hook
│   │   ├── registry.mjs                         # Collects every targets/*.mjs, so a new harness needs no edit here
│   │   ├── common.mjs                           # Shared template reading and read-only role detection
│   │   └── targets/                             # claude, opencode, codex, cursor, copilot, antigravity (four have tests)
│   ├── install/                                 # The installer parts that install.sh sources
│   │   ├── lib.sh                               # Tool lookup, destination states, backup names, digests, entry lists
│   │   ├── digest.sh                            # Directory listing and equality helpers behind the digests
│   │   ├── place.sh                             # Link or copy one entry, with backup and restore
│   │   ├── prereq.sh                            # Tier and tool checks, read from tiers.tsv
│   │   ├── targets.sh                           # The 10 targets, detection, selection, install steps
│   │   ├── check.sh                             # --check
│   │   ├── update.sh                            # --update and prune
│   │   ├── uninstall.sh                         # --uninstall
│   │   ├── sprites.sh                           # Sprite agents for six harnesses
│   │   ├── tiers.tsv                            # Tool table: tool, required_from, capability lost
│   │   ├── windows-core.ps1                     # install.ps1 helpers: paths, digests, markers, judging a destination
│   │   └── windows-ops.ps1                      # install.ps1 target choice, install, -Update, -Check, -Uninstall
│   ├── bootstrap.sh                             # Pinned-release bootstrap: tag only, SHA-256 checked before extraction
│   ├── bootstrap-install.test.mjs               # Bootstrap: a good release, refusals, cleanup, resume hint
│   ├── bootstrap-validation.test.mjs            # Bootstrap: tag rule, checksum file, truncated and hostile archives
│   ├── bootstrap-network.test.mjs               # Bootstrap: https only, redirects with curl and wget (loopback servers)
│   ├── release/
│   │   └── build-archive.sh                     # Deterministic git archive plus .sha256 for a release tag
│   ├── install-*.test.mjs                       # Installer tests (baseline, targets, check, update, uninstall, copy, sprites, ps1, ...)
│   ├── block-git-writes.test.mjs                # Blocked and allowed command tables for the git guard hook
│   ├── skipif-registry-audit.mjs                # Tally and classify skip_if predicates across all plans
│   ├── ultra-plan-runner.mjs                    # ultra-plan/v1 DAG runner + visual map contract
│   ├── ultra-plan-runner.test.mjs               # Contract tests for the runner
│   ├── sync-snippets.mjs                        # Drift guard: snippets/ <-> Snipset database
│   ├── sync-snippets.test.mjs                   # Normalization + drift-detection tests
│   ├── export-opencode-history.mjs              # OpenCode SQLite session history -> Obsidian notes mirror
│   ├── lib/                                     # Exporter & chunk utilities (db, redact, note-name, sync-writer, etc.)
│   │   ├── install-sandbox.mjs                  # Temp HOME and a limited PATH for the installer tests
│   │   └── prereq.mjs                           # Reads scripts/install/tiers.tsv (shared with validate-skill.mjs)
│   ├── plan-publish.mjs                         # Publish plans into the Obsidian vault (one-way mirror)
│   ├── plan-publish.test.mjs                    # Publish, idempotency, drift, and refusal tests
│   ├── plan-publish-registry.mjs                # Vault + project registry and destination paths
│   ├── plan-publish-registry.test.mjs           # Config, project resolution, enumeration tests
│   ├── plan-publish-frontmatter.mjs             # Pure ultra-plan/v1 -> PARA frontmatter transform
│   ├── plan-publish-frontmatter.test.mjs        # Merge rules, related-link, title fallback tests
│   ├── plan-closeout.mjs                        # Close-out gaps, --readiness from skip_if, --audit of merged plans left open
│   ├── pr-registry.mjs                          # PR session slots: derived branch/worktree, recorded repo, state machine, merge order
│   ├── pr-registry.test.mjs                     # Collision, terminal-state, and merge-order guards
│   ├── plan-issue-sync.mjs                      # Plan -> GitHub issue mirror (one-way, hash-keyed)
│   ├── plan-issue-sync.test.mjs                 # Action-matrix and real-argv/stdin guards
│   ├── graphify-sync.mjs                        # Union repo Markdown chunk nodes into graphify-out/graph.json
│   ├── graphify-sync.test.mjs                   # Remap, idempotency, retention, and gate tests
│   ├── vault-index.mjs                          # Vault index scanner & worklist generator
│   ├── vault-index-verify.mjs                   # Verify coverage, privacy boundaries, and graphify read paths
│   ├── vault-index-rebuild.mjs                  # Rebuild merged knowledge graph from structural + semantic chunks
│   ├── vault-index-cluster.mjs                  # Leiden clustering pass for knowledge graph
│   └── plan-mirror-check.sh                     # Local drift watchdog (systemd --user timer, check only)
├── snippets.manifest.json                      # Maps trigger prompts to Snipset database slots
├── plans.publish.json                          # Vault path, destination template, and project roots for the plan mirror (local config, gitignored; plans.publish.example.json is the committed template)
├── plan.issues.json                            # Project -> owner/repo for the plan-issue mirror (local config, gitignored; plan.issues.example.json is the committed template)
├── pr.registry.json                            # Live PR session slots (gitignored; per-machine coordination state)
├── snippets/                                    # Copy-paste trigger prompts
│   ├── orkestrasi-brainstorm.md                # Brainstorm intent lock (keyword: brn)
│   ├── orkestrasi-ngoding-plan.md               # Plan + TDD + mandatory subagent fan-out (keyword: ;')
│   ├── orkestrasi-debugging.md                  # RCA + mandatory hypothesis-parallel subagents (keyword: ';)
│   ├── orkestrasi-pr.md                         # PR delivery, review, and topological batch merge (keyword: ;;')
│   ├── orkestrasi-pr-review.md                  # Standalone PR review & verification gate (keyword: prr)
│   ├── orkestrasi-overnight.md                  # Approved plan to verified PR while away, never merges (keyword: ovn)
│   └── cmd-*.md                                 # Ten short command snippets (mrg err apv dnn sts rsm cln aud prm fbk)
├── templates/                                   # Companion templates (blank scaffolds)
│   ├── brainstorm-intent-template.md           # Brainstorm intent lock, task list A/B/C/D, & approval gate
│   ├── spec-template.md                         # Architectural design spec, no file paths
│   ├── implementation-plan-template.md          # Visual work breakdown & task mapping
│   ├── spike-report-template.md                 # Timeboxed exploratory spike & hypotheses
│   ├── systematic-debugging-log-template.md     # Feedback loop, ranked hypotheses & RCA log
│   ├── verification-checklist-template.md       # Multi-layer proof & sign-off checklist
│   ├── handoff-template.md                      # Session handoff - resume from exact state
│   ├── progress-log-template.md                 # Persistent task state across sessions
│   ├── adr-template.md                          # Architecture Decision Record with decision tree
│   ├── subagent-contract-template.md            # Subagent task contract & parent audit gate
│   ├── vault-index-subagent-contract.md         # Subagent contract for note reading & semantic extraction
│   ├── code-review-template.md                  # Reviewer output contract & verdict
│   ├── deep-research-report-template.md         # Citation-grounded long-form research report
│   ├── follow-up-injection-template.md          # Session-close debt sweep & follow-up question
│   ├── pull-request-template.md                 # PR body, local evidence table, delivery metadata
│   ├── pr-review-template.md                    # Remote PR review, coverage table, binary verdict
│   └── session-learning-ledger-template.md      # Self-learning ledger for operational mistakes
├── vault-index/                                 # Subagent-extracted semantic vault knowledge graph
│   ├── manifest.json                            # Vault files, sha256 hashes, byte sizes, and node counts
│   └── semantic/                                # Subagent chunk outputs (chunk-*.json)
└── skills/
    ├── super-ultra-code-plan/                   # Full skill package with bundled templates & examples
    │   ├── SKILL.md -> ../../Super Ultra Code Plan Implementation.md
    │   ├── templates -> ../../templates
    │   ├── examples -> ../../examples
    │   ├── mermaid.config.json -> ../../mermaid.config.json
    │   └── mermaid.dark.config.json -> ../../mermaid.dark.config.json
    ├── sucp-rules/SKILL.md                      # Phase skill: shared operating rules (loaded every run)
    ├── sucp-brainstorm/SKILL.md                 # Phase skill: Step 2 path process and deep research
    ├── sucp-plan/SKILL.md                       # Phase skill: Step 3 writing plans and GitHub issue sync
    ├── sucp-tdd-debug/SKILL.md                  # Phase skill: Step 4 TDD and systematic debugging
    ├── sucp-verify-deliver/SKILL.md             # Phase skill: Step 5 verification and PR delivery
    ├── sucp-debt-sweep/SKILL.md                 # Phase skill: Step 6 debt sweep (scans code for defer: markers), plan closeout decision, learning harvest
    └── sucp-overnight/SKILL.md                  # Phase skill: unattended run from approved plan to verified PR

TinyFish is documented inside the master skill itself, in the 🌐 Web Evidence & Retrieval (TinyFish) section: the four-rung escalation ladder (search → fetch_content → run_web_automation → create_browser_session), the parameter sets that matter, the run-management and cost rules, and the gotchas. It used to ship as a separate vendored skill (skills/use-tinyfish/, deployed by a now-removed install.sh §6b); that split is retired because two sources of truth had drifted, and the CLI-only copy never described the MCP tools an agent actually calls. One master skill, one set of rules.

The skill installs through skills/super-ultra-code-plan/, which is a set of symlinks into the repo root rather than a copy. The master file stays single-sourced, and render-diagrams.sh skips symlinked files so the same diagram is never rendered twice.

Scripts without a section of their own

The tree lists only some of scripts/, and later sections document most of the rest. These have no section, so this table is where they are described. Each line comes from the script's own header comment. Test files (*.test.mjs) sit next to the script they cover and are omitted.