sneakoscope 0.6.0 → 0.6.3

package/README.md

@@ -1,10 +1,18 @@
 <p align="center">
-  <img src="docs/assets/sneakoscope-codex-logo.svg" alt="Sneakoscope Codex logo" width="180">
+  <img src="https://raw.githubusercontent.com/mandarange/Sneakoscope-Codex/main/docs/assets/sneakoscope-codex-logo.svg" alt="Sneakoscope Codex logo" width="180">
 </p>
 
 <h1 align="center">Sneakoscope Codex</h1>
 
-Sneakoscope Codex is a zero-runtime-dependency Node.js harness for running Codex CLI in a more controlled project workflow. It adds mandatory clarification before autonomous work, a Ralph no-question execution loop, H-Proof completion gates, conservative database safety checks, bounded logs/storage, and deterministic GX visual context cartridges.
+<p align="center">
+  <a href="https://www.npmjs.com/package/sneakoscope"><img alt="npm version" src="https://img.shields.io/npm/v/sneakoscope.svg"></a>
+  <a href="https://www.npmjs.com/package/sneakoscope"><img alt="weekly downloads" src="https://img.shields.io/npm/dw/sneakoscope.svg"></a>
+  <a href="https://github.com/mandarange/Sneakoscope-Codex"><img alt="GitHub stars" src="https://img.shields.io/github/stars/mandarange/Sneakoscope-Codex?style=flat"></a>
+  <a href="https://www.npmjs.com/package/sneakoscope"><img alt="license" src="https://img.shields.io/npm/l/sneakoscope.svg"></a>
+  <img alt="node >=20.11" src="https://img.shields.io/badge/node-%3E%3D20.11-339933.svg">
+</p>
+
+Sneakoscope Codex is an update-aware, zero-runtime-dependency Node.js harness for running Codex CLI in a more controlled project workflow. It adds mandatory clarification before autonomous work, a Ralph no-question execution loop, Codex multi-agent Team orchestration, AutoResearch-style experiment loops, H-Proof completion gates, conservative database safety checks, bounded logs/storage, and deterministic GX visual context cartridges.
 
 ```bash
 npm i -g sneakoscope
@@ -17,46 +25,74 @@ Global installation is the default and recommended setup. During `sks setup` or
 
 ## One-Prompt LLM Install
 
-If you are using Codex App, ChatGPT, Claude Code, Cursor, or another coding agent, copy this prompt into the agent from your target project directory:
+If you are using Codex App, ChatGPT, Claude Code, Cursor, or another coding agent, copy the whole block below into the agent from your target project directory. The agent should install SKS, initialize the project, verify the setup, and show the available commands in one pass.
 
 ````text
-You are installing Sneakoscope Codex in the current project. Do the setup end to end without asking follow-up questions unless a command needs user approval.
+Install Sneakoscope Codex in the current project end to end. Do not ask follow-up questions unless a command requires user approval.
 
 Repository:
 https://github.com/mandarange/Sneakoscope-Codex.git
 
 Requirements:
 - Node.js must be >=20.11.
-- Codex CLI is installed separately; if missing, report that @openai/codex must be installed or SKS_CODEX_BIN must be set.
-- Prefer safe, local verification. Do not modify application source files unless needed for SKS setup.
+- Codex CLI is installed separately. If it is missing, report that `@openai/codex` must be installed or `SKS_CODEX_BIN` must be set.
+- Use the published npm package for normal installs.
+- Do not modify application source files unless needed for SKS setup.
 
 Run:
 ```bash
-npm i -g git+https://github.com/mandarange/Sneakoscope-Codex.git
+npm i -g sneakoscope
 sks setup
+sks update-check
 sks doctor --fix
 sks selftest --mock
 sks commands
+sks dollar-commands
 ```
 
-If the global command is not on PATH, use:
+If npm reports `ENOTEMPTY`, `EEXIST`, or a broken old global package:
 ```bash
-npx -y -p git+https://github.com/mandarange/Sneakoscope-Codex.git sks setup
-npx -y -p git+https://github.com/mandarange/Sneakoscope-Codex.git sks doctor --fix
+npm uninstall -g sneakoscope
+npm i -g sneakoscope
+sks setup
+sks doctor --fix
 ```
 
-After setup, explain these outputs to the user:
+If `sks` is not on PATH:
+```bash
+npx -y -p sneakoscope sks setup
+npx -y -p sneakoscope sks doctor --fix
+npx -y -p sneakoscope sks selftest --mock
+npx -y -p sneakoscope sks commands
+npx -y -p sneakoscope sks dollar-commands
+```
+
+For project-only install:
+```bash
+npm i -D sneakoscope
+npx sks setup --install-scope project
+npx sks update-check
+npx sks doctor --fix --install-scope project
+npx sks selftest --mock
+npx sks commands
+npx sks dollar-commands
+```
+
+Finish by reporting pass/fail and explaining only these generated outputs:
 - `.sneakoscope/` mission state and policy
 - `.codex/config.toml` Codex App profiles
 - `.codex/hooks.json` SKS hook integration
 - `.codex/skills/` local Codex App skills
+- `.codex/agents/` local Codex App multi-agent roles
 - `.codex/SNEAKOSCOPE.md` Codex App quick reference
 - `AGENTS.md` repository rules
 
-Show the user how to discover commands:
+Show command discovery:
 ```bash
 sks help
+sks update-check
 sks commands
+sks usage team
 sks usage ralph
 sks quickstart
 sks codex-app
@@ -68,19 +104,14 @@ Tell the user they can use these prompt commands inside Codex App:
 $DF 글자 색 바꿔줘
 $DF 내용을 영어로 바꿔줘
 $SKS show me available workflows
+$Team agree on the best plan and implement with specialists
 $Ralph implement this with mandatory clarification
 $Research investigate this idea
+$AutoResearch improve this workflow with experiments
 $DB check this migration safely
 ```
 ````
 
-After SKS is installed, you can print this prompt again from the CLI:
-
-```bash
-sks install-prompt
-sks install-prompt --project
-```
-
 ## Repository
 
 ```bash
@@ -89,6 +120,8 @@ npm i -g git+https://github.com/mandarange/Sneakoscope-Codex.git
 
 Source repository: <https://github.com/mandarange/Sneakoscope-Codex.git>
 
+Use the registry install (`npm i -g sneakoscope`) for normal users. The GitHub install path is intended for testing an unreleased commit.
+
 Local development checkout:
 
 ```bash
@@ -131,8 +164,10 @@ Use `$` prompt commands inside Codex App or another coding agent when you want t
 ```text
 $DF        fast design/content fix
 $SKS       general Sneakoscope workflow/help
+$Team      multi-agent team orchestration
 $Ralph     clarification-gated Ralph mission
 $Research  frontier research mission
+$AutoResearch iterative experiment loop
 $DB        database/Supabase safety check
 $GX        deterministic visual context
 $Help      command and workflow help
@@ -162,6 +197,7 @@ This creates the app-facing control surface:
 .codex/config.toml       Codex App profiles for SKS Ralph, research, and default work
 .codex/hooks.json        Codex App hook entrypoints routed through SKS guards
 .codex/skills/           local project skills for Ralph, DB safety, GX, research, and design work
+.codex/agents/           local Codex subagent roles for Team consensus, implementation, DB safety, and QA
 .codex/SNEAKOSCOPE.md    quick reference for using SKS inside Codex App
 AGENTS.md                repository rules loaded by Codex agents
 .sneakoscope/            mission state, gates, logs, policy, GX cartridges, and reports
@@ -172,6 +208,7 @@ Inside Codex App, you can ask the agent to use the local SKS control surface, fo
 ```text
 $DF 글자 색 바꿔줘
 $DF 내용을 영어로 바꿔줘
+$Team agree on the plan, then implement it with a fresh specialist team.
 Use Sneakoscope Ralph mode to prepare this task.
 Run the latest Ralph mission with the sealed decision contract.
 Use SKS DB safety before touching database or Supabase files.
@@ -259,7 +296,11 @@ sks research run latest --max-cycles 3
 - **Sealed decision contract**: `ralph answer` validates answers and writes `decision-contract.json`.
 - **No-question Ralph loop**: after `ralph run` starts, Ralph must resolve ambiguity with the sealed contract instead of asking the user.
 - **Research mode**: `research` runs a frontier-discovery loop for non-obvious hypotheses, falsification, novelty ledgers, and testable experiments.
-- **Prompt pipeline and `$` routes**: user prompts are lightly optimized by default, and Codex App users can force routes such as `$DF`, `$Ralph`, `$Research`, `$DB`, and `$GX`.
+- **Prompt pipeline and `$` routes**: user prompts are lightly optimized by default, and Codex App users can force routes such as `$DF`, `$Team`, `$Ralph`, `$Research`, `$AutoResearch`, `$DB`, and `$GX`.
+- **Team orchestration**: `sks team` and `$Team` prepare a Codex multi-agent flow where planning agents debate options, the parent agent seals one objective, planning agents are closed, and a fresh implementation team handles disjoint work in parallel.
+- **AutoResearch loop**: open-ended improvement tasks use a small experiment cycle: program, hypothesis, experiment, metric, keep/discard, falsification, and honest conclusion.
+- **Update-aware hooks**: before work, SKS checks for a newer published package and asks whether to update now or skip for the current conversation only.
+- **Honest Mode finish**: final answers must include an evidence-aware verification pass before claiming the goal is complete.
 - **Fast DF mode**: `$DF` handles small design/content edits like color, copy, labels, spacing, and translation without unnecessary Ralph, Research, or evaluation loops.
 - **Database guard**: destructive DB operations, production writes, unsafe Supabase MCP configuration, and direct live SQL mutations are blocked or warned on.
 - **H-Proof done gate**: completion requires supported critical claims, reviewed DB safety state, acceptable visual/wiki drift, and required test evidence.
@@ -268,6 +309,64 @@ sks research run latest --max-cycles 3
 - **Visual cartridges**: `gx` creates deterministic SVG/HTML visual context from `vgraph.json` and `beta.json`; no generated-image service is required.
 - **Design artifact skill**: `sks init` installs a local skill for high-fidelity HTML/UI/prototype work with design-context gathering and rendered verification.
 
+## FAQ For Search And AI Answers
+
+### What is Sneakoscope Codex?
+
+Sneakoscope Codex is a Codex CLI harness for safer autonomous software work. It combines update checks, Codex App hooks, multi-agent Team orchestration, Ralph no-question execution, database safety guards, H-Proof completion gates, and bounded runtime state.
+
+### Does Sneakoscope Codex support Codex multi-agent teams?
+
+Yes. `sks setup` enables Codex `multi_agent`, creates `.codex/agents/*.toml` custom agents, and installs a `$Team` workflow for planning debate, consensus, fresh implementation workers, review, and final integration.
+
+### Does Sneakoscope Codex replace Codex CLI?
+
+No. `@openai/codex` is installed separately. Sneakoscope Codex supervises project workflow, hooks, safety policy, state, and local skills around Codex CLI and Codex App.
+
+### Why star the GitHub repository?
+
+Stars help developers discover a lightweight Codex workflow harness focused on database safety, multi-agent orchestration, update hygiene, honest completion checks, and practical autonomous coding loops.
+
+## Team Workflow
+
+Team mode uses Codex subagents/custom agents as an orchestration protocol rather than a single long-running worker. `sks setup` enables `multi_agent`, sets agent concurrency limits, and installs local agent role files under `.codex/agents/`.
+
+```text
+team planning
+  -> spawn read-only/explorer specialists for code paths, risks, DB safety, tests, and options
+  -> synthesize one agreed objective with constraints and acceptance criteria
+  -> close planning agents
+
+fresh implementation team
+  -> assign disjoint write scopes to implementation workers
+  -> run work in parallel only when ownership does not overlap
+  -> review with QA and DB safety specialists
+  -> parent orchestrator integrates, verifies, and reports evidence
+```
+
+Create a Team mission:
+
+```bash
+sks team "implement this feature safely"
+```
+
+Inside Codex App, use:
+
+```text
+$Team agree on the best plan, then implement with specialists
+```
+
+The generated Team artifacts are:
+
+```text
+.sneakoscope/missions/<MISSION_ID>/team-plan.json
+.sneakoscope/missions/<MISSION_ID>/team-workflow.md
+.codex/agents/team-consensus.toml
+.codex/agents/implementation-worker.toml
+.codex/agents/db-safety-reviewer.toml
+.codex/agents/qa-reviewer.toml
+```
+
 ## Ralph Workflow
 
 ```text
@@ -298,12 +397,20 @@ Core invariants:
 
 ## Commands
 
-All examples below use `sks`, but the same commands can be run with the `sneakoscope` alias.
+There are two command surfaces:
+
+- **Terminal CLI commands**: run in a shell as `sks ...` or `sneakoscope ...`.
+- **Prompt `$` commands**: type inside Codex App or another coding agent prompt, not in a shell.
+
+All terminal examples below use `sks`, but the same commands can be run with the `sneakoscope` alias.
+
+### Terminal CLI
 
 ```bash
 sks help [topic]
+sks update-check [--json]
 sks commands [--json]
-sks usage [install|setup|ralph|research|db|codex-app|df|dollar|eval|gx]
+sks usage [install|setup|team|ralph|research|db|codex-app|df|dollar|eval|gx]
 sks quickstart
 sks install-prompt [--project]
 sks codex-app
@@ -343,7 +450,7 @@ sks eval compare --baseline old.json --candidate new.json [--json]
 sks eval thresholds
 
 sks hproof check [mission-id|latest]
-sks team "task"
+sks team "task" [--json]
 sks gx init [name]
 sks gx render [name] [--format svg|html|all]
 sks gx validate [name]
@@ -358,6 +465,45 @@ sks stats [--json]
 
 `sks memory` is currently an alias for garbage collection/retention handling.
 
+### Prompt $ Commands
+
+Use these by typing them at the start of a prompt in Codex App or another coding agent:
+
+```text
+$DF <small design/content request>
+$SKS <general Sneakoscope request>
+$Team <multi-agent team request>
+$Ralph <clarification-gated mission request>
+$Research <research/discovery request>
+$AutoResearch <iterative experiment request>
+$DB <database or Supabase safety request>
+$GX <visual context request>
+$Help <command/help request>
+```
+
+Examples:
+
+```text
+$DF 글자 색 파란색으로 바꿔줘
+$DF 내용을 영어로 바꿔줘
+$DF Change the CTA label to "Start"
+$Ralph 결제 실패 재시도 로직 개선
+$Research LLM 에이전트 평가 방법론 조사
+$DB 이 migration 안전한지 검사해줘
+$GX 현재 아키텍처를 시각 컨텍스트로 만들어줘
+$Help 사용 가능한 명령어 알려줘
+```
+
+`$DF` is the fast path for simple design/content edits. It is intentionally scoped to the requested change and should not run Ralph, Research, eval, or broad redesign loops unless you explicitly ask.
+
+To inspect these routes from the terminal:
+
+```bash
+sks dollar-commands
+sks df
+sks usage dollar
+```
+
 ## Research Mode
 
 Research mode is for exploratory work where the desired output is a possible new insight, mechanism, prediction, or experiment, not a summary. It uses a frontier-discovery loop:
@@ -480,6 +626,7 @@ sks hproof check latest
 .codex/config.toml    Codex profiles used by Sneakoscope Codex
 .codex/hooks.json     hook entrypoints
 .codex/skills/        Codex App local project skills
+.codex/agents/        Codex App custom agents for Team mode
 .codex/SNEAKOSCOPE.md Codex App quick reference
 .agents/skills/       Sneakoscope Codex helper skills
 AGENTS.md             managed repository rules block
@@ -575,12 +722,13 @@ npm run repo-audit
 npm run packcheck
 npm run selftest
 npm run sizecheck
+npm run release:check
 npm run doctor
 ```
 
-`npm run repo-audit` checks tracked files for risky local paths and high-confidence secret material such as private keys, npm/GitHub/OpenAI-style tokens, local MCP configs, DB dumps, and credential files. It is included in `prepack` and `prepublishOnly`.
+`npm run repo-audit` checks tracked files for risky local paths and high-confidence secret material such as private keys, npm/GitHub/OpenAI-style tokens, local MCP configs, DB dumps, and credential files. It is included in `release:check` and `prepublishOnly`. The package intentionally does not define `prepack`; GitHub installs should not trigger npm's heavier git-dependency preparation path for normal users.
 
-`npm run sizecheck` blocks accidental package bloat before `npm pack` or `npm publish`. Defaults: packed tarball `<=96 KiB`, unpacked package `<=320 KiB`, package files `<=40`, and each tracked file `<=256 KiB`. Override only for an intentional release with `SKS_MAX_PACK_BYTES`, `SKS_MAX_UNPACKED_BYTES`, `SKS_MAX_PACK_FILES`, or `SKS_MAX_TRACKED_FILE_BYTES`.
+`npm run sizecheck` blocks accidental package bloat during `release:check`, `publish:dry`, and `npm publish`. Defaults: packed tarball `<=96 KiB`, unpacked package `<=320 KiB`, package files `<=40`, and each tracked file `<=256 KiB`. Override only for an intentional release with `SKS_MAX_PACK_BYTES`, `SKS_MAX_UNPACKED_BYTES`, `SKS_MAX_PACK_FILES`, or `SKS_MAX_TRACKED_FILE_BYTES`.
 
 `npm run selftest` uses the mock path and does not call a model. Live Ralph runs require a working Codex CLI installation and authentication.
 

package/docs/PERFORMANCE.md

@@ -36,7 +36,7 @@ The accuracy metric is not a live model task score. It is a deterministic proxy
 - `@openai/codex` is no longer bundled. Users install Codex separately or set `SKS_CODEX_BIN`.
 - Optional Rust source is in `crates/` for the Git repo, but is excluded from the npm package by the `files` allowlist.
 - GX rendering uses only built-in Node.js APIs and ships as source in the npm package.
-- `npm run sizecheck` enforces package limits before pack/publish: `<=96 KiB` packed, `<=320 KiB` unpacked, `<=40` package files, and `<=256 KiB` per tracked file by default.
+- `npm run sizecheck` enforces package limits during `release:check`, `publish:dry`, and publish: `<=96 KiB` packed, `<=320 KiB` unpacked, `<=40` package files, and `<=256 KiB` per tracked file by default.
 
 ## Memory leaks
 

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "sneakoscope",
   "displayName": "Sneakoscope Codex",
-  "version": "0.6.0",
-  "description": "Sneakoscope Codex: database-safe, performance-bounded Codex CLI harness with Ralph no-question loop, H-Proof gates, deterministic GX visual context, and TriWiki compression.",
+  "version": "0.6.3",
+  "description": "Sneakoscope Codex: update-aware, database-safe Codex CLI harness with multi-agent Team orchestration, Ralph no-question execution, autoresearch-style loops, and H-Proof gates.",
   "type": "module",
+  "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mandarange/Sneakoscope-Codex.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mandarange/Sneakoscope-Codex/issues"
+  },
   "bin": {
     "sks": "bin/sks.mjs",
     "sneakoscope": "bin/sks.mjs"
@@ -28,10 +36,10 @@
     "doctor": "node ./bin/sks.mjs doctor",
     "packcheck": "find bin src scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check",
     "sizecheck": "node ./scripts/sizecheck.mjs",
-    "publish:dry": "npm --cache /tmp/sks-npm-cache pack --dry-run",
+    "release:check": "npm run repo-audit && npm run packcheck && npm run selftest && npm run sizecheck",
+    "publish:dry": "npm run release:check && npm --cache /tmp/sks-npm-cache pack --dry-run",
     "publish:npm": "npm --cache /tmp/sks-npm-cache publish --access public",
-    "prepack": "npm run repo-audit && npm run packcheck && npm run selftest && npm run sizecheck",
-    "prepublishOnly": "npm run repo-audit && npm run packcheck && npm run selftest && npm run sizecheck"
+    "prepublishOnly": "npm run release:check"
   },
   "keywords": [
     "sneakoscope",
@@ -39,9 +47,19 @@
     "sks",
     "cli",
     "ai-agent",
+    "ai-agents",
     "harness",
+    "codex-cli",
+    "codex-app",
+    "multi-agent",
+    "subagents",
+    "agent-orchestration",
+    "agent-team",
     "ralph",
     "research",
+    "autoresearch",
+    "honest-mode",
+    "update-check",
     "hypothesis",
     "discovery",
     "llm-wiki",