atavi 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -18,3 +18,12 @@
 - add `migrate` command for safe workspace schema upgrades
 - add memory import/export helpers for `.atavi/memory`
 - add release-surface verification and npm-based CI coverage
+- add starter prompt files for Codex, Claude, and Gemini
+
+## 0.1.1
+
+- strengthened host guidance and starter prompts so Codex, Claude, and Gemini
+  are expected to ask clarifying questions, present explicit options when the
+  run shape is ambiguous, and keep visible progress updates flowing during ATAVI
+  startup and execution
+- document the reliable global upgrade command as `npm install -g atavi@latest`

package/HOSTS.md

@@ -51,6 +51,26 @@ Recommended order:
 
 Use the existing workspace when `.atavi/` already exists and passes validation.
 
+## Interactive Startup Contract
+
+Before deep repo scanning or pass execution, the host should visibly engage the
+researcher in the terminal or chat surface.
+
+Hosts should:
+
+- announce that ATAVI was detected and that workspace bootstrap is starting
+- state the immediate next step before reading large parts of the repo
+- ask clarifying questions when the brief, objective, or success criteria are
+  ambiguous
+- present explicit option sets when multiple viable scopes, modes, or agent
+  mixes are plausible
+- wait for the researcher when those choices materially change the run
+- emit short progress updates while scanning, validating, and writing artifacts
+- summarize what was learned from the scan before entering pass execution
+
+Hosts should not silently disappear into repository analysis for a long period
+with no visible output.
+
 ## Research Brief Confirmation
 
 Before pass execution begins, confirm `.atavi/brief.md` contains:
@@ -64,6 +84,17 @@ Before pass execution begins, confirm `.atavi/brief.md` contains:
 
 If these are incomplete or contradictory, stop and ask the researcher.
 
+Recommended clarifying topics:
+
+- the concrete research question or product decision to optimize for
+- hard constraints such as time, budget, infra, safety, or launch deadlines
+- whether the run should optimize for novelty search, implementation speed,
+  evidence quality, or risk reduction
+- whether Critic and Synthesist should be enabled for this run
+
+If there are multiple reasonable interpretations, present them as numbered
+options and let the researcher pick instead of choosing silently.
+
 ## Agent Selection Rules
 
 Always include:
@@ -101,6 +132,16 @@ Hosts should also maintain:
 - `.atavi/kill-log.md`
 - `.atavi/run-log.md`
 
+Hosts should keep the user-facing surface alive during execution with short
+status updates such as:
+
+- scanning and summarizing repository context
+- validating `.atavi/` state
+- selecting the active pass and agents
+- finishing POD drafting
+- finishing cross-pollination
+- entering synthesis or decision gating
+
 ## Registry Ownership And Synthesis
 
 Agents propose changes in PODs and CPRs. The host applies accepted changes to
@@ -142,6 +183,13 @@ Recommended load order:
 Codex should keep orchestration file-first and write durable artifacts into
 `.atavi/` rather than relying on hidden memory.
 
+Codex should also provide concise commentary updates before major scans,
+artifact writes, and pass transitions so the user sees visible progress.
+
+Starter prompt:
+
+- `prompts/codex.md`
+
 ## Claude
 
 Recommended load order:
@@ -154,6 +202,13 @@ Recommended load order:
 
 Claude should treat `.atavi/` as the source of truth for resumability and audit.
 
+Claude should ask targeted clarifying questions up front and provide explicit
+choice sets when scope, mode, or agent selection is ambiguous.
+
+Starter prompt:
+
+- `prompts/claude.md`
+
 ## Gemini
 
 Recommended load order:
@@ -166,6 +221,13 @@ Recommended load order:
 
 Gemini should preserve the same file contract as every other host.
 
+Gemini should keep the session visibly interactive with startup confirmation,
+clarifying questions, and brief progress updates during long scans.
+
+Starter prompt:
+
+- `prompts/gemini.md`
+
 ## Failure Modes And Escalation
 
 Hosts should stop and ask the researcher when:

package/README.md

@@ -14,12 +14,21 @@ ATAVI is intentionally thin. The package does not run the research loop for
 you. It ships the protocol, role files, templates, and CLI helpers that a host
 AI can load and execute.
 
+Even though the package is thin, the expected host experience is interactive:
+the host should acknowledge startup, ask clarifying questions when the brief is
+underspecified, present options when there are multiple viable run shapes, and
+keep visible progress updates flowing while it scans and writes `.atavi/`
+artifacts.
+
+ATAVI is published on npm as [`atavi`](https://www.npmjs.com/package/atavi).
+
 ## What You Get
 
 The package ships:
 
 - `protocol/ATAVI.md` as the canonical protocol
 - `protocol/agents/*` for Theorist, Experimentalist, Scout, Critic, and Synthesist
+- `prompts/*` for Codex, Claude, and Gemini starter prompts
 - `templates/*` for briefs, PODs, CPRs, and final reports
 - `bin/atavi.js` as the CLI entrypoint
 - `HOSTS.md` for Codex, Claude, and Gemini loading guidance
@@ -41,6 +50,20 @@ Without web search, Scout mode and full novelty gating are not valid.
 npm install -g atavi
 ```
 
+### Verify the install
+
+```bash
+atavi --version
+atavi --help
+```
+
+### Update an existing global install
+
+```bash
+npm install -g atavi@latest
+atavi --version
+```
+
 ### Run with `npx`
 
 ```bash
@@ -80,6 +103,7 @@ The returned path contains:
 
 - `protocol/ATAVI.md`
 - `protocol/agents/*`
+- `prompts/*`
 - `templates/*`
 
 Your host should load those files plus `.atavi/brief.md`, `.atavi/config.json`,
@@ -95,6 +119,13 @@ Typical flow:
 4. The host writes PODs, CPRs, synthesis records, decision records, registry updates, and memory artifacts into `.atavi/`.
 5. Review `.atavi/ATAVI-REPORT.md` when the run finishes.
 
+Expected host behavior during the run:
+
+- acknowledge that ATAVI was detected
+- ask clarifying questions before long repo scans when the brief is ambiguous
+- present numbered options when mode, scope, or agent mix is unclear
+- provide short progress updates while scanning and writing artifacts
+
 ### 4. Resume or repair later
 
 ```bash
@@ -206,6 +237,12 @@ Then have the host:
 
 See [HOSTS.md](./HOSTS.md) for Codex, Claude, and Gemini-specific loading guidance.
 
+Starter prompts are also shipped under:
+
+- `prompts/codex.md`
+- `prompts/claude.md`
+- `prompts/gemini.md`
+
 ## Development
 
 From a repo checkout:
@@ -224,9 +261,37 @@ node scripts/check-release-surface.js
 node test/run-all.js
 ```
 
+## npm Package
+
+Registry page:
+
+- `https://www.npmjs.com/package/atavi`
+
+Install:
+
+```bash
+npm install -g atavi
+```
+
+Update:
+
+```bash
+npm install -g atavi@latest
+```
+
+Run:
+
+```bash
+atavi --help
+atavi init .
+```
+
 ## Related Docs
 
 - [HOSTS.md](./HOSTS.md)
+- `prompts/codex.md`
+- `prompts/claude.md`
+- `prompts/gemini.md`
 - [ARCHITECTURE.md](./ARCHITECTURE.md)
 - [TESTING.md](./TESTING.md)
 - [CONTRIBUTING.md](./CONTRIBUTING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atavi",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Host-agnostic multi-agent iterative research refinement protocol.",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,7 @@
     "bin/",
     "src/",
     "protocol/",
+    "prompts/",
     "templates/",
     "README.md",
     "HOSTS.md",

package/prompts/claude.md

@@ -0,0 +1,60 @@
+# Claude Starter Prompt
+
+Run the ATAVI protocol for the current project using the local file workspace.
+
+Treat ATAVI as a protocol package, not an application runtime.
+
+## Load Order
+
+1. Run `atavi --path`.
+2. Load `protocol/ATAVI.md`.
+3. Load the relevant role files from `protocol/agents/`.
+4. Load `.atavi/brief.md`, `.atavi/config.json`, and `.atavi/status.md`.
+5. Load `.atavi/registries/claims.md`, `.atavi/registries/experiments.md`,
+   `.atavi/registries/prior-art.md`, `.atavi/conflicts.md`, `.atavi/run-log.md`,
+   and the latest `pass-N/` artifacts if present.
+6. Run `atavi validate .` before a fresh run or `atavi resume-check .` before a
+   resumed run.
+
+## Session Behavior
+
+Before deep scanning:
+
+- confirm that ATAVI is being invoked for this project
+- explain the first files or directories you will inspect
+- ask clarifying questions if the brief, objective, constraints, or decision
+  target are underspecified
+- offer numbered choices when multiple plausible scopes, modes, or agent sets
+  exist
+- wait for the user when those choices materially change the run
+
+During execution:
+
+- provide brief visible progress updates while reading the repo and updating
+  `.atavi/`
+- summarize what the initial scan changed in your understanding
+- do not remain silent for long stretches while analyzing the workspace
+
+## Operating Rules
+
+- Always include Theorist, Experimentalist, and Scout.
+- Add Critic only when risk or irreversibility is high.
+- Add Synthesist only when adjacent domains are likely to help.
+- Keep `.atavi/` as the source of truth for resumability and audit.
+- Do not store canonical registry state only in chat.
+- Do not skip Scout novelty checks for surviving experiments.
+
+## File Contract
+
+- PODs: `.atavi/pass-N/[agent]-pod.md`
+- CPRs: `.atavi/pass-N/cross-pollination/[agent]-cpr.md`
+- Synthesis: `.atavi/pass-N/synthesis.md`
+- Decision gate: `.atavi/pass-N/decision.md`
+- Registries and logs: `.atavi/registries/`, `.atavi/conflicts.md`,
+  `.atavi/kill-log.md`, `.atavi/run-log.md`
+- Memory exports: `.atavi/memory/`
+
+## Expected Outcome
+
+Produce a complete `.atavi/` paper trail that a later host can resume or audit
+without reconstructing hidden context.

package/prompts/codex.md

@@ -0,0 +1,63 @@
+# Codex Starter Prompt
+
+You are running ATAVI in the current project.
+
+Use the local workspace and package files directly. Do not invent hidden state
+or an external orchestration service.
+
+## Load Order
+
+1. Run `atavi --path`.
+2. Read `protocol/ATAVI.md`.
+3. Read the required files in `protocol/agents/`.
+4. Read `.atavi/brief.md`, `.atavi/config.json`, and `.atavi/status.md`.
+5. Read `.atavi/registries/claims.md`, `.atavi/registries/experiments.md`,
+   `.atavi/registries/prior-art.md`, `.atavi/conflicts.md`, `.atavi/run-log.md`,
+   and the latest `pass-N/` artifacts if they exist.
+6. Run `atavi validate .` before a fresh run or `atavi resume-check .` before a
+   resumed run.
+
+## Session Behavior
+
+Before deep scanning:
+
+- acknowledge that you are starting an ATAVI run
+- say what you are going to inspect first
+- ask clarifying questions if the brief, goal, constraints, or success metric
+  are ambiguous
+- present numbered options when there are multiple viable run modes, scopes, or
+  agent mixes
+- wait for the user when those choices materially affect the run
+
+During execution:
+
+- keep visible commentary updates flowing while scanning, validating, and
+  writing artifacts
+- summarize scan findings before entering pass execution
+- do not disappear into long silent repository analysis
+
+## Operating Rules
+
+- The host AI is the orchestrator.
+- Always include Theorist, Experimentalist, and Scout.
+- Add Critic when failure cost is high, the work is irreversible, or the
+  novelty landscape is crowded.
+- Add Synthesist when cross-domain methods are likely to matter.
+- Agents propose changes in PODs and CPRs; you apply accepted changes to the
+  canonical registries during synthesis.
+- Novelty verification is mandatory before an experiment survives.
+- Write every durable artifact into `.atavi/`.
+
+## File Contract
+
+- PODs: `.atavi/pass-N/[agent]-pod.md`
+- CPRs: `.atavi/pass-N/cross-pollination/[agent]-cpr.md`
+- Synthesis: `.atavi/pass-N/synthesis.md`
+- Decision gate: `.atavi/pass-N/decision.md`
+- Final report: `.atavi/ATAVI-REPORT.md`
+- Reusable memory exports: `.atavi/memory/`
+
+## Expected Outcome
+
+Leave the workspace in a resumable, inspectable state with updated registries,
+logs, pass artifacts, and a final report if the run completes.

package/prompts/gemini.md

@@ -0,0 +1,59 @@
+# Gemini Starter Prompt
+
+Use the ATAVI protocol package in this repository to run a file-first
+multi-agent research refinement workflow.
+
+Do not assume hidden orchestration state outside `.atavi/`.
+
+## Load Order
+
+1. Run `atavi --path`.
+2. Read `protocol/ATAVI.md`.
+3. Read the relevant role files in `protocol/agents/`.
+4. Read `.atavi/brief.md`, `.atavi/config.json`, and `.atavi/status.md`.
+5. Read the canonical registries, logs, and most recent `pass-N/` artifacts.
+6. Run `atavi validate .` before a fresh run or `atavi resume-check .` before a
+   resumed run.
+
+## Session Behavior
+
+Before deep scanning:
+
+- confirm that you are starting an ATAVI run
+- tell the user what you will inspect first
+- ask clarifying questions when the brief, objective, constraints, or success
+  criteria are unclear
+- present numbered options when more than one run mode, scope, or agent mix is
+  reasonable
+- wait for the user when those decisions materially affect the run
+
+During execution:
+
+- keep visible progress updates on screen while scanning, validating, and
+  writing artifacts
+- summarize the initial scan before moving into pass execution
+- do not disappear into silent analysis for long periods
+
+## Operating Rules
+
+- The host AI owns orchestration and synthesis.
+- Always include Theorist, Experimentalist, and Scout.
+- Add Critic for high-risk or crowded novelty landscapes.
+- Add Synthesist for cross-domain transfer.
+- Novelty verification is mandatory.
+- Apply accepted changes to the canonical registries during synthesis.
+- Keep the workspace resumable after every pass.
+
+## File Contract
+
+- PODs: `.atavi/pass-N/[agent]-pod.md`
+- CPRs: `.atavi/pass-N/cross-pollination/[agent]-cpr.md`
+- Synthesis: `.atavi/pass-N/synthesis.md`
+- Decision gate: `.atavi/pass-N/decision.md`
+- Final report: `.atavi/ATAVI-REPORT.md`
+- Memory exports: `.atavi/memory/`
+
+## Expected Outcome
+
+Write all durable ATAVI outputs back into `.atavi/` so the process remains
+inspectable, resumable, and host-agnostic.

package/src/cli.js

@@ -7,7 +7,7 @@ import { commandPath } from "./commands/path.js";
 import { commandResumeCheck } from "./commands/resume-check.js";
 import { commandValidate } from "./commands/validate.js";
 
-const VERSION = "0.1.0";
+const VERSION = "0.1.1";
 
 function helpText() {
   return `atavi