Memory Bank Init

STOP - Read before ANY tool call

1. Read {{GUARDRAILS_PATH}}
2. Read _shared/sdd-artifacts/SESSION.md; load session-state for $Cwd
3. If the relevant gate is not approved: STOP - ask user (pt-BR) - do NOT Write/Shell
4. After create or refresh / refresh-light completes: STOP - handoff only (do not start O1/O2/O3 in this skill)
5. This skill body is English; user-facing prompts may be (pt-BR)

Step -1 - Gate check (report in chat before continuing)

Gate check:
[ ] guardrails.mdc read
[ ] SESSION.md read; session-state loaded
[ ] MEMORY-BANK.md read
[ ] STORAGE.md read (bank_root resolution)
[ ] User confirmed current action (sim)
-> If any unchecked: STOP

Skill: memory-bank-init

Credits: memory-bank ideas inspired in part by github/spec-kit; this skill does not run Spec Kit / uv / specify. See docs/CREDITS.md.

Trigger

Invoke when the user asks for: /memory-bank-init, init memory bank, refresh memory bank, or when Orchestrated Delivery Step 0 / Step N (MEMORY-BANK.md) requires create/refresh/refresh-light.

Optional args: create (default if missing), refresh, refresh-light, path to consumer repo.

Outcome

Under the resolved bank_root (STORAGE.md + MEMORY-BANK.md):

memory-bank/
  project-context.md
  tech-stack.json
  architecture.md
  domain-knowledge.md
  conventions.md
  known-risks.md
  database-schema.md      # phase 2 — when relevant / BLOCKING
  api-contracts.md        # phase 2 — when relevant / BLOCKING
  component-catalog.md    # phase 2 — when relevant / BLOCKING
  .inventory/
    sources.json
    gaps.md
    refresh-history.jsonl

MVP files are always required. Phase 2 files: write from templates when Prior/cited content or inventory signals make them relevant. If Prior already has DDL, OpenAPI, or a UI component map, the matching file is BLOCKING (or promote immediately) — empty gaps.md phase 2 is not “optional forever” (MEMORY-BANK.md).

Does not write application code. Does not install Python/uv/specify. Does not place the bank under features/NNN-slug/. Commit bank when product knowledge; never commit secrets. Do not add /memory-bank/ as a required SDD gitignore entry.

Lazy-load

Never by default: do not preload references/command.md before Step -1 gates; do not preload all references/*.md, full PIPELINE/ROSTER packs, or all memory-bank templates at once. Contract first (MEMORY-BANK + STORAGE); after gates load references/command.md for step discovery; load one references/<section>.md per Process step (SKILL-REFERENCE-RETRIEVAL.md).

Process

After gates: Read references/command.md for ordered step discovery (prefer over dumping this Process into prompts). Then load references/<section>.md for procedural tables — not full reference.md.

Step -1b - Caveman Mode (Lite cap)

1. Read {{SDD_ROOT}}/preferences.json (create { "caveman_mode": false, "caveman_level": "full" } if missing).
2. If caveman_mode is false: continue without compression.
3. If true: load {{TOOLKIT_ROOT}}/skills/_shared/caveman/CAVEMAN.md; apply Lite participation cap + prefs caveman_level (Lite skills never escalate); show once: [Caveman] Modo ativo (respostas compactas, level={effective}). Digite caveman off para desativar.
4. Honor caveman on|off|status|lite|full|ultra (and stop caveman / normal mode) during the session.
5. Auto-Clarity + never-compress gates/drafts/paths per CAVEMAN.md.

1. Gate check

Report Step -1 checklist. Load MEMORY-BANK.md and STORAGE.md. STOP if unchecked. Resolve invocation_context per INVOCATION-CONTEXTS.md (IC-DIRECT-ORCHESTRATED): default direct unless Step 0 / Step N parent marks orchestrated. Apply the matching observable table.

2. Resolve target

1. Confirm consumer repo (not toolkit unless explicit).
2. Resolve storage with $Workflow = classic (STORAGE.md).
3. bank_root:
   • repository -> $Cwd/memory-bank/
   • global -> <classic.path>/memory-bank/
4. Never under features/.
5. Mode:
   • create if bank missing/incomplete
   • refresh if user asked or Step 0 marked stale
   • refresh-light if user asked or O3 Step N after code changes

3. Gitignore (repository only)

If storage_mode is repository: ensure SDD .gitignore block per STORAGE.md (/features/ and safety-net patterns only — do not add or require /memory-bank/) before the first bank Write. Commit bank when product knowledge; never commit secrets.

If global: do not edit or suggest SDD patterns in the consumer .gitignore.

4. Confirm before write

Show (pt-BR): mode, full bank_root, files to create/update. Ask:

Posso gravar o memory-bank em '{path}'? (sim / ajustar / cancelar)

Write only after sim.

5. Inventory (read-only scan of consumer)

Prefer script (always scan $Cwd; write inventory under bank_root):

# create (default)
.\scripts\inventory\Invoke-MemoryBankInventory.ps1 -RepoPath "<consumer>" -BankPath "<bank_root>" -AllowCreateInventory

# refresh / refresh-light — pass -Action to match mode for refresh-history.jsonl
.\scripts\inventory\Invoke-MemoryBankInventory.ps1 -RepoPath "<consumer>" -BankPath "<bank_root>" -AllowCreateInventory -Action refresh
.\scripts\inventory\Invoke-MemoryBankInventory.ps1 -RepoPath "<consumer>" -BankPath "<bank_root>" -AllowCreateInventory -Action refresh-light

Output in <bank_root>/.inventory/sources.json:

Exit codes: 0 = ready; 2 = not-ready (still writes sources.json under bank_root/.inventory/ only). Path escape / missing sources / incomplete hash → not-ready + reason (TE01).

Observable wire (required): after the script (or fallback) runs, read status, status_reason, inventory_hash, and inventory_summary from sources.json and include them in the Step 7 report. Do not treat not-ready as silent success — surface the reason before create/refresh file fills. Re-runs preserve paths from existing sources.json plus default discovery.

If script path unavailable, run equivalent Glob/Grep from references/inventory-fallback.md and write only under <bank_root>/.inventory/ (same governance fields).

6. Scaffold or refresh files

Rules:

• Preserve <!-- BEGIN GENERATED: … --> / <!-- END GENERATED: … --> discipline (references/generated-markers.md)
• No secrets - env names / *** only (references/secrets.md)
• Evidence-based domain/architecture; unknowns -> gaps.md
• Phase 2 (database-schema.md, api-contracts.md, component-catalog.md): write from templates when relevant; if Prior/cited already has DDL/OpenAPI/UI map, those files are BLOCKING (promote immediately or - [ ] BLOCKING: until written)
• Versioning / .gitignore: references/versioning.md. Dry-run checks: references/dry-run.md

7. Report + handoff

Report paths written, stack hints, blocking gaps (if any), storage mode, and inventory governance: status / status_reason / inventory_hash / inventory_summary (from Step 5). If status is not-ready, say so explicitly with the reason before handoff.

Handoff examples:

/orchestrate-analyze
/memory-bank-init - refresh
/memory-bank-init - refresh-light

Must not

• Write application / test source
• Create bank under features/NNN-slug/
• Require external CLI tooling (uv, specify, Spec Kit installers)
• Skip confirm-before-write
• Dump entire bank into orchestrator parent context
• Do not ignore IC-DIRECT-ORCHESTRATED — resolve and apply direct vs orchestrated (INVOCATION-CONTEXTS.md)
• Auto-commit
• Edit consumer .gitignore when storage_mode is global
• Add or require /memory-bank/ in .gitignore
• Commit secrets into the bank (keys, tokens, connection strings, raw .env)
• Leave phase 2 as gaps-only when Prior/cited already has DDL, OpenAPI, or a UI component map (those files are BLOCKING — write/promote or - [ ] BLOCKING:)