@jstn-sdk/ma 0.1.5 → 0.1.6

package/docs/getting-started.md

@@ -1,24 +1,169 @@
 # Getting Started
 
-Meta-Architect is a Codex-native runtime layer. Install Codex, install Meta-Architect, launch the runtime posture, then operate through skill tags inside Codex.
+This guide takes Meta-Architect from install to a green-gated skill workflow on a real project.
 
-## Canonical path
+## Goal
 
-Install:
+By the end of this guide you should be able to:
+- install Meta-Architect
+- configure MCP/GitMCP sources
+- run the full architecture-to-build sequence
+- understand how each gate moves
+- diagnose blocked gates
+- use the merge/release path safely
+
+## Prerequisites
+
+- Node.js 20+
+- npm 10+
+- Git 2.30+
+- an MCP-capable runtime
+- network access if you want live `$sage` verification against a real GitMCP server
+
+## 1. Canonical install and launch
+
+Canonical public install:
 
 ```bash
-npm i -g @openai/codex @jstn-sdk/ma
+# Install
+npm i -g @openai/codex@latest @jstn-sdk/ma@latest
+
+# Launch
+ma --madmax --high
+
+# Remove Meta-Architect only
+npm uninstall -g @jstn-sdk/ma
+
+# Remove Meta-Architect and Codex
+npm uninstall -g @jstn-sdk/ma @openai/codex
 ```
 
-Launch:
+That is the default product path. The product experience is the in-session skill workflow in [example/usage-workflow.md](../example/usage-workflow.md). The `ma` command is only a helper for starting or supporting that flow.
+
+## 2. Real usage workflow
+
+Start with the structured `$arch` prompt:
+
+```text
+$arch I want to build: [PROJECT IDEA]
+
+Context:
+- Product type: [web app / mobile app / API / marketplace / agent system / internal tool]
+- Users: [who will use it]
+- Core problem: [what problem it solves]
+- Main features:
+  1. [feature one]
+  2. [feature two]
+  3. [feature three]
+- Constraints:
+  - Budget: [low / medium / high]
+  - Team size: [solo / small / medium]
+  - Timeline: [e.g. 2 weeks MVP, 3 months beta]
+  - Preferred stack: [optional]
+  - Avoid: [optional]
+- Quality priorities:
+  - [e.g. speed, low cost, security, DX, maintainability, scalability]
+- Deployment target:
+  - [Vercel / Docker / VPS / AWS / GCP / local-first / hybrid]
+
+Required output:
+1. Problem framing
+2. Recommended architecture
+3. Stack decision with justification
+4. System components and responsibilities
+5. Data model and storage choices
+6. Auth/security considerations
+7. DX/UX considerations
+8. Delivery plan for v0.1.6
+9. Risks and trade-offs
+10. Decision log
+11. Exact next trigger to run after this
+```
+
+Then continue with:
+
+```text
+$sage
+$flow
+$vet
+$vibe
+$build
+```
+
+Use the full prompt blocks from [example/usage-workflow.md](../example/usage-workflow.md) when you want the exact handoff format between lanes.
+
+## 3. Contributor clone and link
 
 ```bash
-ma --madmax --high
+git clone https://github.com/JustineDevs/meta-architect.git
+cd meta-architect
+npm install
+npm link
+```
+
+Why `npm link` matters:
+- it makes the local helper command available without requiring a global publish step
+
+## 4. Secondary repository setup flow
+
+```bash
+ma setup
+```
+
+Optional interactive session:
+
+```bash
+ma
 ```
 
-Operate inside Codex with:
+Expected effects:
+- `.codex/agents/` exists
+- `.codex/prompts/` exists
+- local `.ma/skills/`, `.ma/evidence/`, `.ma/context/`, `.ma/specs/`, `.ma/plans/`, and `.ma/runbook.md` are seeded
+- `mcp/`, `docs/`, and `sprint/` surfaces exist
+- `ma` opens Codex with the Meta-Architect helper posture when run with no arguments
+
+Expected output:
+
+```text
+meta-architect setup
+====================
+ready: .codex/agents
+ready: .codex/prompts
+ready: .ma/skills
+ready: .ma/evidence
+ready: .ma/context
+ready: .ma/specs
+ready: .ma/plans
+ready: mcp
+ready: docs
+ready: docs/qa
+ready: sprint
+```
+
+This setup path is secondary to the canonical in-session skill workflow. Use it when you need local repo scaffolding.
+
+## 4.1 Understand the two surfaces
+
+Meta-Architect works in two simple ways:
+
+- terminal commands
+- in-session skills
+
+Terminal commands are normal shell commands:
+
+```bash
+ma setup
+ma init
+ma sdk-path
+ma status
+ma run '$arch'
+```
+
+In-session skills are prompts used after you are already inside Codex:
 
 ```text
+$maestro
 $arch
 $sage
 $flow
@@ -27,62 +172,299 @@ $vibe
 $build
 ```
 
-## Runtime expectations
+Easy rule:
+- `ma ...` = terminal helper command
+- `$...` = in-session skill
+
+`ma setup` and `ma init` currently do the same thing:
+- they create local `.ma/` support files
+- they prepare context, specs, plans, evidence, and runbook files
+- they do not automatically run the skill workflow
+
+`ma sdk-path` prints the installed packaged support-bundle root for relevant files such as prompts, MCP files, sprint files, scripts, plugin metadata, and templates.
+
+## 5. Configure MCP / GitMCP
+
+Edit:
+- `mcp/servers.json`
+- `mcp/collections.json`
+- `mcp/fallback.json`
+
+Minimum live example:
+
+```json
+{
+  "category": "meta-list",
+  "repo": "sindresorhus/awesome",
+  "endpoint": "https://gitmcp.io/sindresorhus/awesome"
+}
+```
+
+Recommended first set:
+- `sindresorhus/awesome`
+- `dzharii/awesome-typescript`
+- `sbilly/awesome-security`
+
+See [docs/mcp-setup.md](./mcp-setup.md) for endpoint policy and evidence semantics.
+
+## 6. Secondary helper flow
 
-- Codex is the host runtime.
-- Meta-Architect is the runtime extension.
-- The skill tags are the primary product surface.
-- `ma` is a runtime launcher plus a small maintenance/helper interface.
+```bash
+ma idea "Build a real-time collaborative whiteboard for product teams"
+```
 
-## When to use helper commands
+Expected effects:
+- an idea decision entry is appended to `.ma/decisions.json`
+- `idea_status = CLEAR`
 
-Use helper commands only when you need scripted repo validation or repo-local scaffolding:
+If this fails:
+- ensure the idea text is not empty
+- inspect `.ma/decisions.json` for malformed local data
+
+## 7. Run the helper skill sequence
+
+### 5.0 Workflow manager
+
+```bash
+ma run '$maestro'
+```
+
+Expected effects:
+- reads the current gate state
+- recommends the best next step
+- writes `.ma/plans/maestro.md`
+- records an advisory decision entry
+
+Generated or updated:
+- `.ma/decisions.json`
+- `.ma/plans/maestro.md`
+
+### 5.1 Architecture
 
 ```bash
-ma status
-ma idea "Build a real-time collaborative whiteboard"
 ma run '$arch'
+```
+
+Expected effects:
+- a structured first-pass architecture blueprint is appended
+- `architecture_status = APPROVED`
+
+Generated or updated:
+- `.ma/decisions.json`
+- `.ma/release.json`
+- `.ma/context/project.md`
+- `.ma/specs/architecture.md`
+- `.ma/plans/implementation.md`
+
+### 5.2 Evidence
+
+```bash
 ma run '$sage'
+```
+
+Expected effects:
+- `architecture_status` must already be approved
+- configured GitMCP endpoints are validated
+- the latest architecture summary is used as the probe query basis
+- the first configured live source is probed when live mode is enabled
+- `.ma/evidence/sources.json` is updated
+- `evidence_status` becomes:
+  - `VERIFIED` on a real successful live probe
+  - `PARTIAL` when configured evidence exists but live proof is incomplete or disabled
+  - `MISSING` when no usable approved source exists
+
+Generated or updated:
+- `.ma/evidence/sources.json`
+- `.ma/decisions.json`
+- `.ma/release.json`
+- `.ma/specs/evidence.md`
+
+If this fails:
+- check endpoint URLs in `mcp/servers.json`
+- ensure architecture was approved first
+- verify network access
+- rerun after correcting the endpoint or environment
+
+### 5.3 Logic
+
+```bash
 ma run '$flow'
+```
+
+Expected effects:
+- a structured first-pass logic/state review is appended
+- `logic_status = GREEN` when current prerequisites and transition modeling are acceptable
+- `logic_status = RED` when prerequisite gates are not ready
+
+Generated or updated:
+- `.ma/specs/logic.md`
+
+### 5.4 Security
+
+```bash
 ma run '$vet'
+```
+
+Expected effects:
+- `.ma/evidence/audits.json` and `.ma/evidence/cves.json` are updated
+- `security_status = GREEN` on a baseline pass
+- `security_status = RED` when prerequisite gates are not ready
+
+Generated or updated:
+- `.ma/specs/security.md`
+
+### 5.5 Experience
+
+```bash
 ma run '$vibe'
+ma run '$vibe' --waive --reason "Accepted for this release line"
+```
+
+Expected effects:
+- `.ma/evidence/outcomes.json` is updated
+- `experience_status = GREEN` on a baseline pass
+- `experience_status = RED` when prerequisite gates are not ready
+- `experience_status = WAIVED` when the waiver path is used explicitly
+
+Generated or updated:
+- `.ma/specs/experience.md`
+
+## 8. Inspect gate status
+
+```bash
+ma status
+```
+
+Expected green-state output:
+
+```text
+Meta-Architect Status
+=====================
+Idea: CLEAR
+Architecture: APPROVED
+Evidence: VERIFIED
+Logic: GREEN
+Security: GREEN
+Experience: GREEN
+Build: LOCKED
+Next allowed triggers:
+$build
+```
+
+## 9. Unlock and run build planning
+
+```bash
 ma run '$build'
-ma doctor
+```
+
+Expected effects:
+- build gate is evaluated
+- if allowed, `build_status = READY`
+- branch suggestions are printed
+- worktree commands are suggested
+- `.ma/plans/build.md` is updated
+
+Expected output shape:
+
+```text
+Build gate is green.
+Suggested branches:
+- feature/ui
+- feature/api
+Optional worktree commands:
+git worktree add ../ui feature/ui
+git worktree add ../api feature/api
+```
+
+If `$build` fails:
+- run `ma status`
+- read the blocking statuses
+- fix the corresponding upstream lane
+- rerun that lane, then rerun `$build`
+
+## 10. Example walkthrough: collaborative whiteboard
+
+```bash
 ma setup
+ma idea "Build a collaborative whiteboard with live cursors and shared boards"
+ma run '$arch'
+ma run '$sage'
+ma run '$flow'
+ma run '$vet'
+ma run '$vibe'
+ma status
+ma run '$build'
 ```
 
-`ma setup` repairs or seeds repo-local support files such as:
-- `AGENTS.md`
-- `.codex/`
-- `.omx/`
-- `mcp/`
-- `templates/`
+If you want an interactive Codex session during the walkthrough, start it separately with `ma`.
 
-That path is secondary. The main experience remains the Codex session launched with `ma --madmax --high`.
+What should happen:
+- `$arch` records a structured first-pass blueprint
+- `$sage` binds major choices to configured GitMCP-backed sources
+- `$flow` records the kernel’s baseline state review for the mission
+- `$vet` records a baseline security review
+- `$vibe` records baseline DX/UX guidance
+- `$build` suggests bounded concerns like `feature/ui` and `feature/api`
 
-## MCP / GitMCP
+Related mission:
+- [missions/collaborative-whiteboard/mission.md](../missions/collaborative-whiteboard/mission.md)
 
-Meta-Architect expects approved GitMCP endpoints for evidence-heavy lanes such as `$sage`.
+## 9. Merge and release path
 
-Edit:
-- `mcp/servers.json`
-- `mcp/collections.json`
-- `mcp/fallback.json`
+After implementation work is complete:
+
+```bash
+ma merge feature/ui development
+ma release development prod
+```
+
+Expected effects:
+- merge only succeeds for `feature/* -> development`
+- release only succeeds for `development|release/* -> prod`
+- final statuses advance to:
+  - `build_status = DONE`
+  - `merge_status = MERGED_TO_DEVELOPMENT`
+  - `release_status = SHIPPED_TO_PROD`
+
+## 10. Files generated or updated during a normal run
+
+- `.ma/decisions.json`
+- `.ma/release.json`
+- `.ma/evidence/sources.json`
+- `.ma/evidence/audits.json`
+- `.ma/evidence/cves.json`
+- `.ma/evidence/outcomes.json`
+- `.ma/context/project.md`
+- `.ma/specs/architecture.md`
+- `.ma/specs/evidence.md`
+- `.ma/specs/logic.md`
+- `.ma/specs/security.md`
+- `.ma/specs/experience.md`
+- `.ma/plans/implementation.md`
+- `.ma/plans/build.md`
+- `.ma/runbook.md`
 
-See [docs/mcp-setup.md](./mcp-setup.md) for exact-endpoint policy and fallback rules.
+These are local product artifacts created by the runtime. They are not a reason to bypass gate logic manually.
 
-## Release-aware usage
+## 11. If a gate fails
 
-`$build` is locked until all upstream review gates are green or explicitly waived by policy.
+Rule:
+- do not edit statuses manually
+- rerun the correct upstream command
+- use `ma status` as the authority
 
-Before claiming a release is ready, make sure:
-- `npm run release:check` passes
-- [docs/release-spec.md](./release-spec.md) still matches behavior
-- [docs/qa/release-readiness-0.1.5.md](./qa/release-readiness-0.1.5.md) matches the actual release line
+Common examples:
+- `evidence_status = MISSING` -> fix `mcp/servers.json`, rerun `$sage`
+- `logic_status = RED` -> fix upstream evidence/architecture issues, rerun `$flow`
+- `security_status = RED` -> resolve issues surfaced by `$vet`
+- `experience_status = RED` -> rerun `$vibe` after clearing prerequisites
+- `experience_status = WAIVED` -> verify the waiver reason recorded in `.ma/release.json`
 
 ## Related docs
 
+- [README.md](../README.md)
 - [Skills Reference](./skills.md)
 - [MCP Setup](./mcp-setup.md)
 - [Release Spec](./release-spec.md)
+- [Skills Publishing](./skills-publishing.md)
 - [Plugin Bundle](../plugins/meta-architect/README.md)

package/docs/installed-sdk.md

@@ -0,0 +1,60 @@
+# Installed Support Bundle
+
+Meta-Architect installs two things into the active Codex home:
+
+1. skills under `CODEX_HOME/skills/`
+2. a support bundle under `CODEX_HOME/meta-architect-sdk/`
+
+The support bundle exists so skills and helper paths can use relevant packaged files without guessing where they live.
+
+## Canonical support bundle path
+
+Default:
+
+```text
+~/.codex/meta-architect-sdk/
+```
+
+If `CODEX_HOME` is set, use:
+
+```text
+$CODEX_HOME/meta-architect-sdk/
+```
+
+You can print the exact active path with:
+
+```bash
+ma sdk-path
+```
+
+## What is installed there
+
+- `mcp/`
+- `sprint/`
+- `prompts/`
+- `scripts/`
+- `plugins/meta-architect/`
+- `templates/`
+- `docs/README.md`
+- `asset-manifest.json`
+
+## Why this exists
+
+- skills can rely on a standard installed asset root
+- helper paths can repair missing support assets automatically
+- packaged references do not depend on a source checkout
+- the product can use relevant packaged files without path guessing
+
+## Contract
+
+When Meta-Architect needs packaged support files, prefer the installed support bundle first.
+
+Examples:
+- MCP starter files -> `meta-architect-sdk/mcp/`
+- sprint references -> `meta-architect-sdk/sprint/`
+- Codex prompt assets -> `meta-architect-sdk/prompts/`
+- helper scripts -> `meta-architect-sdk/scripts/`
+- plugin metadata -> `meta-architect-sdk/plugins/meta-architect/`
+- templates -> `meta-architect-sdk/templates/`
+
+The in-session skill flow is still primary. This bundle only standardizes packaged asset access.

package/docs/mcp-setup.md

@@ -1,136 +1,5 @@
 # MCP / GitMCP Setup
 
-Meta-Architect uses MCP as the protocol layer and GitMCP as the remote evidence surface for curated OSS repositories.
-
-## Files that matter
-
-- `mcp/servers.json`
-- `mcp/collections.json`
-- `mcp/fallback.json`
-
-These are committed product config files, not hidden runtime state.
-
-## How server mappings work
-
-### `mcp/servers.json`
-
-Defines the approved exact GitMCP-backed repositories the runtime may probe.
-
-Each entry should include:
-- `category`
-- `repo`
-- `endpoint`
-
-Example:
-
-```json
-{
-  "category": "security",
-  "repo": "sbilly/awesome-security",
-  "endpoint": "https://gitmcp.io/sbilly/awesome-security"
-}
-```
-
-### `mcp/collections.json`
-
-Defines the committed lane-to-category policy:
-- which categories belong to `arch`
-- which belong to `sage`
-- which belong to `vet`
-
-The current runtime probes `mcp/servers.json` directly, while `mcp/collections.json` remains the committed contract for how category routing should be understood and evolved.
-
-### `mcp/fallback.json`
-
-Defines the documented fallback rule for:
-- `https://gitmcp.io/docs`
-
-Fallback is a policy declaration, not permission to skip exact endpoints when those are already known.
-
-## Endpoint strategy
-
-Preferred rule:
-- use repo-specific `https://gitmcp.io/{owner}/{repo}` endpoints
-- avoid generic discovery when an exact approved repo is already known
-
-This keeps recommendations scoped and auditable.
-
-## GitMCP collection examples
-
-Useful committed examples:
-- `sindresorhus/awesome`
-- `dzharii/awesome-typescript`
-- `rust-unofficial/awesome-rust`
-- `sbilly/awesome-security`
-- `awesome-selfhosted/awesome-selfhosted`
-
-## How `$sage` uses live evidence
-
-Current `$sage` behavior:
-1. requires `architecture_status = APPROVED`
-2. reads `mcp/servers.json`
-3. validates endpoint shape
-4. derives the query from the latest architecture summary
-5. opens a live GitMCP SSE connection when live probing is enabled
-6. negotiates the MCP message endpoint
-7. runs `tools/list`
-8. runs one repo-specific tool call
-9. writes probe metadata into `.omx/evidence/sources.json`
-
-This is enough to provide real runtime evidence for the first configured approved source. It is not a full multi-source reasoning engine yet.
-
-## VERIFIED vs PARTIAL vs MISSING
-
-### `VERIFIED`
-- at least one approved endpoint is configured
-- a real live probe succeeds
-- usable evidence is written
-
-### `PARTIAL`
-- configured evidence exists
-- but live proof is incomplete, disabled, or degraded
-
-### `MISSING`
-- no valid approved source exists
-
-Do not silently mark evidence as verified when the live source did not succeed.
-
-## What to do when MCP is unavailable
-
-If MCP or GitMCP is unavailable:
-- keep evidence partial or missing
-- record the failure explicitly
-- do not fabricate evidence
-- fix the endpoint or network condition first
-- rerun `$sage`
-
-## How to keep committed MCP config honest
-
-- commit real or intentionally documented example endpoints only
-- do not leave fake placeholders in production config
-- update this file if category policy changes
-- treat endpoint drift as a release-sensitive change
-
-## Example setup workflow
-
-1. edit `mcp/servers.json`
-2. confirm categories in `mcp/collections.json`
-3. inspect fallback policy in `mcp/fallback.json`
-4. ensure `$arch` already approved the architecture
-5. run:
-
-```bash
-ma run '$sage'
-```
-
-6. inspect:
-- `.omx/evidence/sources.json`
-- `.omx/decisions.json`
-- `.omx/release.json`
-
-## Related surfaces
-
-- [README.md](../README.md)
-- [docs/skills.md](./skills.md)
-- [docs/release-spec.md](./release-spec.md)
-- [plugins/meta-architect/README.md](../plugins/meta-architect/README.md)
+1. Add repo-specific GitMCP endpoints in `mcp/servers.json`.
+2. Confirm categories in `mcp/collections.json`.
+3. Use `https://gitmcp.io/docs` only when no approved exact endpoint exists.