feat: bootstrap repo: add project profile, session memory, and plan s…

.context/decisions.md

@@ -0,0 +1,3 @@
+# Decisions
+
+<!-- Append laconico, formato: - YYYY-MM-DD: decisione — perché -->

.context/issues.md

@@ -0,0 +1,3 @@
+# Issues
+
+<!-- Append laconico, formato: - YYYY-MM-DD: problema — soluzione/stato -->

.context/progress.md

@@ -0,0 +1,10 @@
+# Progress
+
+## Stato attuale
+- (vuoto)
+
+## Fatto
+- (vuoto)
+
+## Prossimi passi
+- (vuoto)

.gitignore

@@ -48,5 +48,16 @@ coverage/
 
 # Internal orchestration state (session memory + drafts)
 .context/
+!.context/
+!.context/progress.md
+!.context/decisions.md
+!.context/issues.md
 plan/
-.opencode/
+!plan/
+!plan/README.md
+.opencode/
+!.opencode/
+!.opencode/PROJECT-PROFILE.md
+
+# Output files
+output*.txt

.opencode/PROJECT-PROFILE.md

@@ -0,0 +1,18 @@
+# Stack
+
+- Language: TypeScript
+- Framework: React
+- Package Manager: Bun
+- Build Tool: Vite
+- Test Framework: None detected
+- CI/CD: None detected
+
+# Structure
+
+- Monorepo: No
+- Detected Manifests:
+  - package.json
+
+# Code Graph
+
+- Code Graph: absent — optional, see CRG integration notes

AGENTS.md

@@ -4,7 +4,7 @@
 
 This document defines the **strict orchestrator** role for `orchestrator` and the contracts for all subagents. `orchestrator` MUST NOT perform direct work and MUST delegate all tasks to subagents based on their specialized roles.
 
-> **Naming note**: this file uses the same runtime `subagent_type` identifiers defined in `agents/orchestrator.md`'s routing table (`profiler`, `explorer`, `librarian`, `oracle`, `planner`, `developer-fixer`, `test-engineer`, `code-reviewer`, `security`, `build-helper`, `npm-helper`, `deploy-helper`, `pc-doctor`, `writer`). Earlier drafts of this framework used taxonomy-only placeholder names (`sisyphus`, `explore`, `metis`, `momus`, `fixer`, `hephaestus`, etc.) that have no corresponding runtime agent file — those names are retired. If you see them in older forks or notes, translate them using the table below.
+> **Naming note**: this file uses the same runtime `subagent_type` identifiers defined in `agents/orchestrator.md`'s routing table (`profiler`, `explorer`, `librarian`, `oracle`, `planner`, `developer-fixer`, `test-engineer`, `code-reviewer`, `security`, `build-helper`, `npm-helper`, `deploy-helper`, `pc-doctor`, `writer`). The `pc-doctor` and `writer` agents live in `extras/` rather than `agents/`; only their file location differs, not their runtime IDs. Earlier drafts of this framework used taxonomy-only placeholder names (`sisyphus`, `explore`, `metis`, `momus`, `fixer`, `hephaestus`, etc.) that have no corresponding runtime agent file — those names are retired. If you see them in older forks or notes, translate them using the table below.
 
 ---
 
@@ -62,10 +62,10 @@ This document defines the **strict orchestrator** role for `orchestrator` and th
 | `build-helper` | TypeScript/Vite/webpack/build-tool errors. | Scoped fixes |
 | `npm-helper` | npm/Node dependency, install, cache issues. | Scoped fixes |
 | `deploy-helper` | CI/CD pipeline and deploy platform failures. | Scoped fixes |
-| `pc-doctor` | Windows/local environment, PATH, services. | Scoped fixes |
-| `writer` | Technical documentation generation. | Docs only, never executable code |
+| `pc-doctor` | Windows/local environment, PATH, services. Defined in `extras/pc-doctor.md`. | Scoped fixes |
+| `writer` | Technical documentation generation. Defined in `extras/writer.md`. | Docs only, never executable code |
 
-Model assignment (primary/fallback per agent) lives in each `agents/<name>.md` frontmatter, not in this file — this keeps model choice editable per deployment without touching the orchestration contract.
+Model assignment (primary/fallback per agent) lives in each `agents/<name>.md` (or `extras/<name>.md` for `pc-doctor` and `writer`) frontmatter, not in this file — this keeps model choice editable per deployment without touching the orchestration contract.
 
 ---
 
@@ -101,3 +101,70 @@ Model assignment (primary/fallback per agent) lives in each `agents/<name>.md` f
 - Subagents MUST adhere to their defined contracts in `agents/<name>.md`. Violations MUST be reported to `orchestrator` for escalation.
 - All delegated tasks MUST include a reference to this document for clarity.
 - This file governs orchestration and delegation; `CONTRIBUTING.md` governs engineering discipline (secrets hygiene, git hygiene, definition of done). Where they overlap, this file wins for routing decisions and `CONTRIBUTING.md` wins for how the work itself is done.
+
+---
+
+## Prompt-Assembly Stable-Prefix Contract
+
+This section locks down the **repository-controlled stable prefix** of the prompt assembly. It is the contract that any future assembler implementation, cache key, or review tool MUST honor. It documents what is already enforced by the test suite; it does not introduce new behavior.
+
+### Boundary
+
+The repository-controlled stable prefix consists only of the following prompt-source files:
+
+- `AGENTS.md` — the single root file.
+- `agents/*.md` — every Markdown file in the `agents/` directory.
+- `extras/*.md` — every Markdown file in the `extras/` directory (when the directory exists).
+
+Anything else — `tests/`, `skills/`, `.context/`, `plan/`, `docs/`, the site/ directory, lockfiles, etc. — is out of scope for the stable prefix.
+
+### Explicit Exclusions
+
+The following paths are **deliberately excluded** from the stable prefix:
+
+- `.opencode/context/` — user-local; not a repository-controlled prompt source.
+- `.opencode/models.config.json` — user-local configuration; not a prompt source.
+- OpenCode-native cache internals — the cache implementation is owned by the runtime, not by this repository. This contract does not, and must not, assert anything about OpenCode's internal cache key format, hashing strategy, eviction policy, or storage layout.
+
+The exclusion of `.opencode/context/` and `.opencode/models.config.json` is rule-based: even if those paths exist on disk, they MUST NOT appear in the stable prefix.
+
+### Deterministic Enumeration Order
+
+The assembler MUST concatenate boundary files in exactly this order:
+
+1. `AGENTS.md` (first, when present).
+2. `agents/*.md` paths, sorted ascending by relative path (lexicographic, forward slashes).
+3. `extras/*.md` paths, sorted ascending by relative path (when the directory exists).
+
+Within each bucket the order is strictly sorted; across buckets the order is strictly `AGENTS.md` → `agents/` → `extras/`. No bucket may interleave with another. Two independent enumerations of the same repository MUST produce identical lists; the sort is the source of determinism.
+
+### Frontmatter Key Order
+
+The canonical top-level frontmatter key order for files under `agents/` and `extras/` is:
+
+```
+description, mode, model, temperature, tools, permission
+```
+
+Present keys MUST appear in this order. Absent keys are skipped (subsequence semantics, not strict permutation). Nested keys inside `tools:` and `permission:` blocks are out of scope — this contract does not prescribe their order or shape. Top-level keys outside the canonical list are rejected.
+
+### Boundary Baseline
+
+The committed baseline of the boundary lives at `tests/fixtures/prompt-prefix-boundary.txt`. It lists every boundary file exactly once, in sorted order, using forward slashes. Any change to the set of boundary files (addition, removal, rename) MUST update the baseline in the same change.
+
+The relevant guard tests are:
+
+- `tests/frontmatter-order.test.ts` — asserts the canonical top-level frontmatter key order (and the current `mode: primary` file set).
+- `tests/assembly-order.test.ts` — asserts the deterministic `AGENTS.md` → sorted `agents/` → sorted `extras/` enumeration.
+- `tests/stable-prefix-boundary.test.ts` — asserts the boundary exactly matches the committed baseline and explicitly excludes `.opencode/context/` and `.opencode/models.config.json`.
+
+### Known Discrepancy (Out of Scope)
+
+The repository currently has a pre-existing two-primary discrepancy: `agents/orchestrator.md` and `agents/security.md` both declare `mode: primary`. This contract does **not** assert that there is a single primary agent, does not prescribe a resolution, and does not authorize changing either value. Reconciling the spec's single-primary wording with the existing two-primary reality is left to a separate decision.
+
+### Scope of This Contract
+
+- This section documents repository-controlled prompt-source invariants. It does not modify OpenCode's internal cache implementation, model-preset values, or routing behavior.
+- Adding, removing, or renaming a boundary file is a contract change: update the baseline and the relevant tests in the same change.
+- `.opencode/context/` remains user-local and excluded by explicit user decision; do not edit or un-ignore it.
+- The model-preset mismatch remains out of scope; this contract does not mention a resolution.

README.md

@@ -60,11 +60,11 @@ The orchestrator itself never edits `auth.ts` — it only routes, checkpoints, a
 | 🏗️ `build-helper` / `npm-helper` / `deploy-helper` / `pc-doctor` | Toolchain/CI/environment triage | Scoped by failure type |
 | ✍️ `writer` | Documentation generation | |
 
-Full contracts, permissions, and model fallbacks are defined in each `agents/*.md` file and summarized in `AGENTS.md`.
+Full contracts, permissions, and model fallbacks are defined in each `agents/*.md` file (with the `pc-doctor` and `writer` specialists living in `extras/*.md` instead) and summarized in `AGENTS.md`.
 
 ## 🚀 Quickstart — native OpenCode (no plugin)
 
-1. Clone this repo, or copy just `agents/`, `skills/`, `command/`, `AGENTS.md`, and `CONTRIBUTING.md` into your target project.
+1. Clone this repo, or copy just `agents/`, `extras/`, `skills/`, `command/`, `AGENTS.md`, and `CONTRIBUTING.md` into your target project.
 2. Place them where OpenCode looks for them:
    - **Project-only**: `.opencode/agents/`, `.opencode/skills/`, `.opencode/command/`, and `AGENTS.md` at the project root.
    - **Every project on your machine**: `~/.config/opencode/agents/`, `~/.config/opencode/skills/`, `~/.config/opencode/command/`, `~/.config/opencode/AGENTS.md`.

agents/build-helper.md

@@ -3,6 +3,7 @@ description: >-
   Build-tool error specialist for TypeScript, Vite, webpack, Rollup, esbuild, Sass, PostCSS, and native
   modules.Diagnoses from error output and applies minimal fixes. Does not refactor application code.
 mode: subagent
+model: ollama/deepseek-v4-flash:cloud
 temperature: 0.2
 permission:
   task: deny
@@ -41,7 +42,6 @@ permission:
     build-debug: allow
     npm-debug: allow
     dev-cleanup: allow
-model: ollama/deepseek-v4-flash:cloud
 ---
 # Build Helper
 

agents/code-reviewer.md

@@ -2,8 +2,8 @@
 description: >-
   Systematic code reviewer that finds bugs, security flaws, and design risks before release, then ranks them and
   recommends concrete fixes.
-mode: primary
-model: ollama/minimax-m3:cloud
+mode: subagent
+model: opencode-go/minimax-m3
 temperature: 0.2
 tools:
   code-review-graph_detect_changes_tool: true

agents/deploy-helper.md

@@ -3,6 +3,7 @@ description: >-
   CI/CD and deployment specialist for GitHub Actions, Vercel, and Netlify. Diagnoses pipeline and deploy failures,
   reads PROJECT-PROFILE.md to know the target platform before acting. Does not touch application logic.
 mode: subagent
+model: ollama/deepseek-v4-flash:cloud
 temperature: 0.2
 permission:
   task: deny
@@ -36,7 +37,6 @@ permission:
     github-actions-cicd: allow
     npm-debug: allow
     dev-cleanup: allow
-model: ollama/deepseek-v4-flash:cloud
 ---
 # Deploy Helper
 

agents/developer-fixer.md

@@ -3,7 +3,7 @@ description: >-
   Unified implementation agent. Operates in Fixer mode (exact-spec execution, zero extra research) when given a
   complete task spec, or Developer mode (strict TDD) when given a partial/exploratory request.
 mode: subagent
-model: ollama/minimax-m3:cloud
+model: opencode-go/minimax-m3
 temperature: 0.2
 tools:
   edit: true

agents/npm-helper.md

@@ -3,6 +3,7 @@ description: >-
   npm and Node.js error specialist for dev folders. Diagnoses install/runtime/peer-dep/cache/native-module issues and
   applies minimal fixes. Does not modify application source code.
 mode: subagent
+model: ollama/deepseek-v4-flash:cloud
 temperature: 0.2
 permission:
   task: deny
@@ -35,7 +36,6 @@ permission:
     "*": deny
     npm-debug: allow
     dev-cleanup: allow
-model: ollama/deepseek-v4-flash:cloud
 ---
 # npm Helper
 

agents/orchestrator.md

@@ -59,8 +59,8 @@ Every `task` delegation MUST set `subagent_type` to one of the runtime IDs below
 | `build-helper` | TypeScript, Vite, webpack, Rollup, or build errors. |
 | `npm-helper` | npm/Node dependency, install, cache, or runtime issues. |
 | `deploy-helper` | CI/CD pipeline failures (GitHub Actions) and deploy errors (Vercel, Netlify). |
-| `pc-doctor` | Windows PATH, environment, services, registry, or task issues. |
-| `writer` | Technical documentation generation. |
+| `pc-doctor` | Windows PATH, environment, services, registry, or task issues. Defined in `extras/pc-doctor.md` (not in `agents/`). |
+| `writer` | Technical documentation generation. Defined in `extras/writer.md` (not in `agents/`). |
 
 Prefer the most specific runtime ID above. Fall back to a higher-capability agent only when the primary match is unavailable or clearly insufficient.
 
@@ -177,3 +177,38 @@ The orchestrator MUST NOT:
 - Skip this gate for read-only or advisory agents (`explorer`, `librarian`, `oracle`, `code-reviewer`, `security`, `planner`, `profiler`) -- they never write application files and are exempt.
 
 This gate applies regardless of which routing path led to the delegation (direct `developer-fixer` delegation, `planner` -> `developer-fixer` handoff, or any `build-helper`/`deploy-helper`/`npm-helper`/`test-engineer` fix).
+## Task Handoff
+
+### Objective
+
+Implement <feature/fix> without modifying <constraints>.
+
+### Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Relevant tests green
+
+### Relevant Context
+
+- Files: `src/...`, `tests/...`
+- Symbols: `Namespace.Type.Method`
+- Architecture decision: <one sentence>
+- Constraints: <one sentence>
+
+### Plan Reference
+
+`.context/plans/<task-id>.md`
+
+### Required Validation
+
+`<test/lint/build command>`
+
+## Response Economy
+
+For delegation, output only:
+1. Selected subagent runtime ID;
+2. Task handoff following the required schema;
+3. Brief routing rationale, maximum 80 words.
+
+Never restate repository context, explorer output, plan content, tool logs, or prior agent responses. Persist detailed findings to the designated artifact and reference its path.

agents/security.md

@@ -3,6 +3,7 @@ description: >-
   Security engineer focused on vulnerability detection, threat modeling, and secure coding practices. Use for
   security-focused code review, threat analysis, or hardening recommendations.
 mode: primary
+model: opencode-go/kimi-k3
 temperature: 0.2
 permission:
   "*": deny
@@ -22,7 +23,6 @@ permission:
     "*": deny
     security: allow
     code-quality: allow
-model: opencode-go/kimi-k3
 ---
 # Security Auditor
 

agents/test-engineer.md

@@ -3,7 +3,7 @@ description: >-
   QA engineer that designs focused test strategy, writes behavior-level tests, analyzes coverage, and uses the prove-it
   pattern to reproduce bugs.
 mode: subagent
-model: ollama/minimax-m3:cloud
+model: opencode-go/minimax-m3
 temperature: 0.3
 tools: {}
 permission:

docs/SETUP-OPENCODE-STUDIO.md

@@ -32,4 +32,4 @@ If your profile's orchestrator behavior doesn't match what's in this kit's `AGEN
 
 ## Multiple profiles, multiple rosters
 
-Because each profile has its own config directory, you can install different versions of the kit (or different agent subsets) per profile — e.g., one profile tuned for a .NET backend with `dotnet-conventions` and `deploy-helper` prioritized, another for a frontend repo leaning on `angular-patterns` and `build-helper`. Just re-run `install.sh studio <profile-name>` for each profile you want it in.
+Because each profile has its own config directory, you can install different versions of the kit (or different agent subsets) per profile — e.g., one profile tuned for a .NET backend with `skills/examples/dotnet-conventions` and `deploy-helper` prioritized, another for a frontend repo leaning on `skills/examples/angular-patterns` and `build-helper`. Just re-run `install.sh studio <profile-name>` for each profile you want it in.