@thebackstoryis/engineering-with-ai 0.2.9

package/skills-src/ewai-phase-evidence/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: ewai-phase-evidence
+description: Guide named business-facing and technical owners through one revision-safe EWAI phase contribution thread with explicit provenance, active persona lenses, owner hand-offs, shared review and immutable supporting evidence. Use when a user asks to open or use Phase Studio, contribute non-technical or technical evidence to Reconcile, Plan, Test Plan, Delivery preparation or Manual QA preparation, review a queued phase contribution, change owner context, prepare a responsibility hand-off, or confirm a phase contribution bundle without changing delivery authority.
+---
+
+# EWAI Phase Evidence
+
+Use the project-local Phase Studio and its governed contribution contract. Keep one shared, attributed thread. Do not create a parallel phase document or infer approval from participation.
+
+## Establish the boundary
+
+1. Perform the required EWAI check-in and use the configured project and SPECS root.
+2. Read the current intent, delivery state and execution integrity before making a substantive claim. Refresh the EWAI Source Map first when repository evidence is material and the index is missing or stale.
+3. Continue only when Phase Studio reports a supported, running profile: Reconcile, Plan, Test Plan, Delivery preparation or Manual QA preparation.
+4. Treat `business`, `technical` and `shared-review` as contribution contexts, never identity, access or permission.
+5. Name the real person holding each context. Keep that accountable person separate from every persona lens.
+
+Do not use this skill to complete a phase, approve Build, accept Manual QA, dispose of security findings, accept risk, deploy, certify or release. Route governed delivery progression through `$ewai-deliver` and its durable human gates.
+
+## Build one evidence thread
+
+1. Select the current server-owned evidence topic.
+2. Ask the standard host-model questions for the phase and owner context.
+3. Engage the small active persona ensemble shown by Phase Studio. Project and core personas plus ordinary host-model reasoning provide a complete baseline. Use premium, personal and project-local personas only when already installed and relevant. Never imitate, download or synchronise a missing persona.
+4. Record each contribution with:
+   - topic;
+   - real contributor and owner context;
+   - one evidence class: `repository-fact`, `participant-statement`, `imported-source`, `persona-hypothesis`, `named-decision` or `unresolved-question`;
+   - bounded statement;
+   - source or provenance;
+   - unresolved questions, conflicts and limitations where applicable.
+5. Preserve earlier attribution. Correct or qualify a claim through a new revision or named resolution; do not silently rewrite who said what.
+
+Personas are advisory lenses. Their output is not participant evidence, validation, legal or specialist assurance, acceptance or approval.
+
+## Change responsibility safely
+
+When focus changes without responsibility moving, switch owner context and save the new revision. Confirm the real named owner and explain which personas joined or left.
+
+When responsibility moves, prepare an owner hand-off containing:
+
+- named source and destination owners;
+- distinct source and destination contexts;
+- reason for the transition;
+- questions for the incoming owner;
+- current revision and SHA-256 digest.
+
+Verify the preview before submission. Resume the same draft after the hand-off. Never copy it into a second competing thread.
+
+## Review without flattening disagreement
+
+Use shared review to show business and technical evidence with original attribution. Preserve unresolved differences and named decision ownership.
+
+For a queued `review-contribution` hand-off:
+
+1. Verify `authority: none`, intent, phase, revision and digest.
+2. Read only the matching project-local draft needed for the review. Do not expose raw premium persona definitions, credentials or unrestricted repository content.
+3. Challenge provenance, missing perspectives, contradictions, acceptance evidence and deliberately unresolved items.
+4. Return proposed changes as advisory feedback. Do not confirm the bundle or alter delivery state on the user's behalf.
+
+## Confirm supporting evidence
+
+Before named confirmation, show:
+
+- current phase, revision and digest;
+- named owners and hand-off history;
+- all evidence classes and sources;
+- conflicts, resolutions, open questions and limitations;
+- active persona metadata and its advisory status;
+- exact project-relative Markdown and JSON destinations.
+
+Confirmation creates paired immutable evidence beneath `SPECS/6.Build/<slug>/phase-contributions/<profile>/`. It remains supporting evidence. The orchestrator must separately reconcile relevant contributions into the required phase artefact and pass the normal deterministic gate, standards sweep, configured independent validation and human approvals.
+
+## Recover safely
+
+- On a stale revision, changed phase, source drift or profile drift, preserve the participant's unsaved text, reload current state and reconcile deliberately.
+- Discard only the disposable runtime draft after explicit confirmation. Never delete confirmed bundles.
+- If state integrity is blocked or the phase is unsupported/completed, remain read-only and route the user to Companion or `$ewai-deliver`.
+- If premium personas are absent, state that optional enrichment is unavailable and continue with the complete baseline.

package/skills-src/ewai-phase-evidence/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Phase Evidence"
+  short_description: "Guide named owners through phase evidence"
+  default_prompt: "Use $ewai-phase-evidence to guide named owners through the current supported delivery phase."

package/skills-src/ewai-pipeline/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: ewai-pipeline
+description: Initialise and operate the portable Engineering With AI Pipeline in a software project. Use when Codex needs to create or inspect a project-local SPECS contract, onboard an existing codebase through Archaeology, discover EWAI technology or persona packs, attach EWAI delivery methodology to a repository, run installation diagnostics, or prepare intent-to-delivery work through EWAI skills and tooling.
+---
+
+# EWAI Pipeline
+
+## Presentation, not a shorter workflow
+
+Keep the complete onboarding and delivery flow. Show four routine status lines, the returned menu at a decision point, and one decision at a time. Retain warnings, blockers and unknown checks with short reasons; technical diagnostics are on request. Progress is one sentence of at most 24 words per meaningful checkpoint. Don't narrate commands, file reads, JSON parsing, policies or internal reasoning. Don't repeat the menu during a selected action. These limits never waive briefing, consent, purpose alignment, standards, Build approval or Manual QA.
+
+Use the `ewai` CLI as the stable interface. Resolve durable knowledge from the `specsRoot` in `.ewai-pipeline/project.json`; do not assume it is `./SPECS`. Keep regenerable runtime state under the workspace's `.ewai-pipeline/`.
+
+## Open the companion
+
+When the first user message says EWAI launched this host, own the complete onboarding conversation. Do not ask the user to copy, paste, or run CLI commands. Licence entry uses the guarded dashboard password form by default; a hidden private terminal prompt is an alternative only when a genuine interactive terminal is available. Never collect a key in chat or shell arguments. Treat commands, JSON, and tool output as internal control-plane details and translate them into concise human language.
+
+1. Determine whether `.ewai-pipeline/project.json` exists and whether its configured SPECS root contains `pipeline.yaml`.
+2. If the project is not initialized, use the launch's project root and existing-code signal. Ask one location question: recommend `./SPECS` for one repository/monorepo or a dedicated knowledge repository for independent repositories. After agreement, run `ewai init --project <resolved-root> --specs <agreed-path> --json` promptly; add `--init-specs-repo` only when local knowledge-repository creation is approved. Do not inspect the installed EWAI source, run `ewai --version`, or perform project Archaeology before init. Version comes from check-in. An uninitialised first response is the location question, not an invented status/menu. Never create a remote repository without separate explicit approval.
+3. Once initialized, run `ewai checkin --project <path> --json` and wait for the complete result.
+   - Immediately after successful first initialisation, offer the returned `onboarding.personaLearning` question: **“Would you like to see how specialist personas could help us analyse this project?”** Offer it before deeper analysis or Archaeology for both new and existing code. Choosing to read opens https://www.conversationalcoding.dev/personas/; it does not buy, activate or download anything. Respect a decline and continue normal onboarding with installed personas. Preserve the human briefing and purpose alignment. Do not repeat first-run onboarding when the project was already initialised at launch.
+4. Always interpret and display the EWAI version and update status, premium entitlement and installed-library status, and dashboard URL. Show `unknown` states with a short reason; never silently omit a check.
+   - The harness is installed and updated only through npm. Offer only the returned npm update action. Never inspect, fetch, or pull the EWAI Git repository for installation or updating, including when working in the harness development checkout.
+5. Ask before any premium install or update. Do not download merely because access exists.
+6. Capture the initial human project briefing. At minimum establish purpose, primary users, desired outcomes, business context, known constraints, and what must not be inferred from current behaviour.
+7. Ask whether the user has a folder of emails, meeting transcripts, documents, research, requirements, or other project material for optional `$ewai-context-import` enrichment. Ask once during onboarding; respect a decline.
+8. If material is supplied, complete its consent, classification, processing-policy, reconnaissance, and persona-routing gates before using it to enrich detailed discovery or Archaeology.
+9. For an existing codebase, only then offer optional Archaeology: explain that it can reconstruct missing documentation from the code, and ask whether the user wants it. Do not run it without acceptance. If declined, continue to Discovery and Doctor; it remains available later. If accepted, require its purpose-alignment and persona-value checkpoints before deep reconstruction; show which installed core, premium, personal, or project personas would improve the bounded passes and ask the user to confirm the ensemble.
+10. Read recent work and render the structured `companion` opening returned by check-in. The opening format is mandatory: report status first, render its heading, and render every action in order as `[id] label`. A narrative-only opening is invalid. Do not replace or precede the menu with a free-form recommendation list. Option **[6] Continue a piece of work** must be present whenever check-in returns it. Include **[7] Read about premium personas** and **[8] Set up premium personas** only when returned: both are absent when premium access is available and the installed pack is verified. Always render **[9] Configure the dashboard**. When `companion.spotlight` is present, render it after the numbered actions as a bounded advisory spotlight: name the work, reason and accountable route, then name each `activePersonas` entry with its tier. Do not present the spotlight as a new menu action or as approval. When `companion.personaSetup` is present, ask its exact optional question after the menu: **“Do you have a premium persona licence, or shall we use the core personas?”** Only then ask the exact returned closing prompt: **“What's on your mind?”**
+11. Treat Companion and persona guidance as advisory. A recommendation or persona cannot create delivery permission, user evidence, specialist assurance, accepted risk or human acceptance. Never let a Companion read trigger premium sync or download; use installed premium personas only when already present.
+12. When check-in returns a pending `dashboardHandoff`, identify it immediately after the numbered menu. If its action is `review-contribution`, verify `authority: none`; when the user confirms, use `ewai_resolve_dashboard_handoff` to mark it `claimed`, invoke `$ewai-phase-evidence`, return advisory feedback, and mark it `completed` without changing delivery state. For `begin` or `continue`, confirmation claims the hand-off, invokes `$ewai-deliver`, and completes it only after the canonical begin/resume transition succeeds. A dashboard selection is never permission to skip a gate or begin writing code.
+
+When the user chooses **[6] Continue a piece of work**:
+
+1. Use `$ewai-deliver`; do not enter the host AI's generic plan mode.
+2. List resumable intent delivery states from EWAI rather than memory.
+3. Let the user choose when more than one work item is plausible.
+4. Invoke the guarded EWAI delivery continue operation for the selected slug.
+5. Reconcile Markdown, structured intent JSON, durable delivery JSON, and SQLite before proceeding.
+6. Resume the exact next canonical phase. Never infer or skip a phase, and never write Build code without the recorded human Build approval.
+
+When the user chooses **[7] Read about premium personas**, offer the fixed public learning page https://www.conversationalcoding.dev/personas/ and open it only when chosen. The visitor can read about perspectives and find purchase choices there. Return to the conversation without acquiring content or changing the project.
+
+Render **[8] Set up premium personas** only when returned. When it or private setup is chosen, use `$ewai-persona-entitlement` with the dashboard's guarded password form by default; hidden terminal configure is an alternative only when a genuine private interactive terminal is available. Explain that submitting the key verifies and installs immediately; do not ask a second download question for that action. Never ask them to paste a key here. Confirm the safe installed/version result and refresh `ewai persona index --project <path> --json` before using the new lenses. Resolve chosen setup before any accepted Archaeology; after failure offer retry or explicit core-only continuation. Retain briefing and purpose alignment. Reading or declining continues core work without acquiring anything. The automatic missing-key question applies only to `companion.personaSetup`, not expired, invalid or unavailable configured licences. Licence management remains available in dashboard Configuration even when [8] is absent. Do not repeat the missing-key question within a conversation after a decline.
+
+When the user chooses **[9] Configure the dashboard**, use `$ewai-dashboard-configuration`. Explain only the views relevant to their needs and save their explicit choices through the shared preferences command. Optional views are off by default; hiding them never disables required checks, hooks, policies, standards or approvals.
+
+Companion menu identifiers (render only the actions actually returned):
+
+1. Capture something new
+2. Pick up a ready intent
+3. Explore an idea and shape connected intents
+4. Explore the Mind Palace, risks, or standards
+5. See recommendations and possible next work
+6. Continue a piece of work
+7. Read about premium personas
+8. Set up premium personas
+9. Configure the dashboard
+
+Without existing work, omit [6]. With available premium access and a verified installed pack, omit [7] and [8]. Keep [9] and never renumber the remaining identifiers.
+
+Keep progress warm and semantic: say what EWAI is trying to understand and what changed in its understanding. Do not narrate shell commands, filenames being opened, JSON parsing, or routine check execution unless the user asks for technical detail or an operation fails.
+
+## Start every project conversation with check-in
+
+When `.ewai-pipeline/project.json` points to a valid SPECS contract, run `ewai checkin --project <path> --json` once before substantive project work. Briefly tell the user:
+
+- the project pipeline-dashboard URL and whether it was started or reused;
+- whether premium persona access is available;
+- whether the premium library is installed and current;
+- whether an EWAI Pipeline update is available.
+- whether the project Mind Palace is tidy or would benefit from housekeeping.
+
+Check-in may start the project-local loopback dashboard and refresh its disposable SQLite projection. It checks licence access and available versions without downloading updates, but it isn't unconditionally read-only: confirmed expiry of the matching team subscription blocks that managed pack and removes it only when the unchanged files can be safely verified. Edited or unsafe files are preserved for investigation but excluded from premium selection. Individual expiry keeps installed personas and stops updates. A failed or unverified provider response isn't proof of expiry; an already confirmed team expiry remains in effect during a later outage. Personal and project personas are never part of that cleanup. When check-in returns `offer-install` or `offer-update`, ask whether the user wants the download. Do not sync merely because access or an update exists. Only after explicit approval run `ewai persona premium sync --project <path> --yes`.
+
+Every new session follows the returned actions, including [9] for Configuration. A missing-key result must also become the actual `companion.personaSetup` question in the conversation, not just a status summary. Keep credentials private and core use optional as described above.
+
+## Keep live work observable
+
+When an intent is actively being delivered, use the EWAI MCP active-work tools so the user can follow material progress in the dashboard:
+
+- start a session when substantive delivery work begins;
+- record handoffs, external reviews, decisions, responses, blockers, human questions, and completed artefacts;
+- resolve a human question when its answer has been applied;
+- finish the session with its real outcome.
+
+Do not publish heartbeat events such as “still working.” Live activity is a decision and evidence stream, not a token-by-token transcript.
+
+## Start or inspect a project
+
+1. Resolve the workspace root from `.ewai-pipeline/project.json`, a default `SPECS/pipeline.yaml`, or `.git`; then use the locator's configured SPECS root.
+2. Initialise a single repository or monorepo with `ewai init --project <path>`. For a workspace of independent repositories, recommend a dedicated knowledge repository and use `ewai init --project <workspace> --specs <knowledge-repository>/SPECS --init-specs-repo` after permission to initialise the local Git repository.
+   - After successful first init, offer `onboarding.personaLearning` before deeper analysis or Archaeology, for new or existing code. Learning is optional and requires no purchase or install; retain the briefing and respect a decline.
+3. Capture a human project briefing, then offer `$ewai-context-import` for any supplied emails, transcripts, documents, or research.
+4. Let Context Import inspect the available persona index, explain which personas improve the analysis, and propose evidence-grounded project actors without confusing advisory personas with real user research.
+5. For existing code, always offer optional Archaeology and wait for acceptance. If declined, continue to Discovery without reconstruction and leave it available later. If accepted, compare repository and imported evidence with the briefing and ask the owner to resolve material discrepancies before deeper reconstruction.
+6. Review and curate Context Import and Archaeology findings; offer self-review/manual filing or an AI-guided walkthrough, and do not promote inferred intent, constraints, personas, or technology choices automatically.
+7. After Archaeology curation, offer to interview the user about upcoming features, interpret an imported roadmap or feature list, or suggest evidence-based product, security, operational, and code-quality recommendations. Keep immature accepted ideas as feature candidates and create full intents only with user approval.
+8. Complete `ewai discover --project <path>` to confirm scope, stack, minimum standards, and compliance triage using the reviewed findings.
+9. Verify it with `ewai doctor --project <path> --json`.
+10. Read `pipeline.yaml` from the configured SPECS root before selecting repositories, packs, or delivery behaviour.
+
+Do not relocate or overwrite an existing SPECS contract through init. Relocation requires an explicit migration that updates the workspace locator and project contract together.
+
+## Discover capabilities
+
+- Run `ewai pack list` to inspect installed core, technology, persona, and organisation packs.
+- Run `ewai persona list --project <path>` to inspect core, personal, and project personas available to a project.
+- Run `ewai persona index --project <path> --json` when a skill needs descriptions, tags, capabilities, tiers, and local paths for persona routing.
+- Use `ewai persona create <slug>` for a reusable personal persona, or add `--scope project --project <path>` for a persona owned by the project.
+- Use `ewai persona path` to locate the personal library. Premium personas are supplied by entitled packs and must not be assumed available.
+- Use `$ewai-shape-intents` when a broad idea, workflow, roadmap item, or capability may need several connected intents. It must present and gain approval for the map before creating any draft.
+- Use `$ewai-intent` to refine one coherent intent, including any approved map membership and relationships.
+- Use `$ewai-architecture` to walk through current or target enterprise/solution architecture for a whole system, bounded capability or domain, intent set, or cross-cutting concern, and prepare reviewable standards, patterns, ADRs, risks, diagrams, and transition records before delivery relies on them.
+- Use `$ewai-standards-check` to verify supplied code, files, change sets, or a whole repository against accepted project-local SPECS standards and create durable review evidence.
+- Use `$ewai-palace-housekeeping` when the user selects the Mind Palace option or check-in reports that project knowledge would benefit from housekeeping.
+
+## Operating boundaries
+
+- Treat the configured SPECS root as versionable project truth. In a multi-repository workspace, prefer a dedicated knowledge-and-delivery repository.
+- Treat `.ewai-pipeline/` as disposable runtime state.
+- Treat Markdown under the configured SPECS root as authoritative over its SQLite projection.
+- Let the configured agent host start the stdio MCP server; do not run a second persistent MCP process.
+- Require human approval before Build when `approvals.build` is `required`.
+- Read the full `validation` contract before scheduling review. Do not infer availability from global machine state, and do not use the active Claude, Codex, or Antigravity orchestrator as its own independent validator.
+- Honour each checkpoint's selected providers, maximum cycles, breadth, depth, and output limit. Standards compliance remains mandatory even when no independent external validator is configured.
+- Never write project outputs into the global EWAI installation.
+- Never carry repository paths or project state from one project into another.
+
+Read [CLI reference](references/cli.md) for command details and [SPECS contract](references/specs-contract.md) when creating or validating project artefacts.

package/skills-src/ewai-pipeline/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Pipeline"
+  short_description: "Run portable Engineering With AI delivery workflows"
+  default_prompt: "Use $ewai-pipeline to open the conversational Engineering With AI companion for this project."

package/skills-src/ewai-pipeline/references/cli.md

@@ -0,0 +1,86 @@
+# EWAI CLI reference
+
+## Project commands
+
+```bash
+ewai install [--project PATH] [--host auto|codex|claude|antigravity] [--mode copy|link]
+ewai init [--project PATH] [--name NAME] [--specs PATH] [--init-specs-repo] [--claude] [--codex] [--antigravity] [--force] [--json]
+ewai checkin [--project PATH] [--json] [--verbose]
+ewai dashboard [--project PATH] [--json]
+ewai server start|status|stop [--project PATH] [--json]
+ewai mcp [--project PATH]
+ewai discover [--project PATH] [--answers FILE] [--stack PACK] [--force] [--json]
+ewai context register FOLDER [--project PATH] --yes [--label NAME] [--classification public|internal|confidential|restricted] [--cloud-processing allowed|denied|unknown] [--exclude RELATIVE_PATH] [--force] [--json]
+ewai archaeology prepare-personas BUNDLE [--project PATH] [--force] [--json]
+ewai archaeology validate-personas BUNDLE [--project PATH] [--json]
+ewai archaeology validate BUNDLE [--project PATH] [--json]
+ewai archaeology prepare-review BUNDLE [--project PATH] [--force] [--json]
+ewai archaeology curate BUNDLE [--project PATH] --yes [--approved-by NAME] [--json]
+ewai validation list [--project PATH] [--orchestrator manual|claude|codex|antigravity] [--json]
+ewai validation set claude|codex|antigravity available|unavailable [--enabled|--disabled] [--project PATH] [--json]
+ewai validation checkpoint implementation-plan|test-plan|code [--cycles N] [--validators auto|PROVIDER,...] [--breadth targeted|change-set|capability|system] [--depth issues-only|issues-and-fixes|analysis-and-recommendations] [--output small|medium|large] [--enabled|--disabled] [--project PATH] [--json]
+ewai doctor [--project PATH] [--json]
+ewai intent create SLUG [--domain DOMAIN] [--title TITLE] [--persona REF:ROLE:DEPTH] [--delivery-shape FILE] [--project PATH] [--json]
+ewai intent map-create FILE --yes [--approved-by NAME] [--project PATH] [--json]
+ewai intent audit-state [--project PATH] [--json]
+ewai afk preflight SLUG [--provider auto|claude|codex|antigravity] [--parallel N] [--project PATH] [--json]
+ewai afk start SLUG [--provider auto|claude|codex|antigravity] [--parallel N] [--timeout-minutes N] [--project PATH] [--json]
+ewai afk status [RUN_ID] [--project PATH] [--json]
+ewai afk pause|resume|cancel RUN_ID [--project PATH] [--json]
+ewai palace refresh [--project PATH] [--json]
+ewai palace status [--project PATH] [--json]
+ewai palace search QUERY [--limit N] [--project PATH] [--json]
+ewai palace tidiness [--project PATH] [--json]
+ewai palace housekeeping [--project PATH] [--json]
+```
+
+Without `--project`, `install` registers EWAI globally. With `--project`, it installs agent skills into that repository. Copy mode is team-friendly; link mode follows the current EWAI checkout.
+
+`init` creates missing project structures and preserves existing files unless `--force` is explicitly supplied. The default SPECS root is `SPECS`. For a workspace containing independent repositories, use `--specs <knowledge-repository>/SPECS --init-specs-repo`; EWAI records that path in `.ewai-pipeline/project.json` and can initialise its containing folder as a dedicated local Git repository. Init does not relocate an existing SPECS contract.
+
+`discover` interviews the project owner or reads a repeatable answers file, then populates the canonical Project SPECS and technology/assurance profile.
+
+`intent map-create` atomically writes one reviewed product-level map and all of its linked draft intents. The JSON or YAML request must use `ewai.intent-map-request/v1`; `--yes` records that the user approved the proposed map. Conversational shaping is handled by `$ewai-shape-intents`, so users should not normally need to prepare this file themselves.
+
+`context register` inventories an explicitly approved source folder without copying its raw content into SPECS. The detailed path and file inventory remain under `.ewai-pipeline/context/`; the committed source registry contains sanitized metadata and a fingerprint. `--yes` represents user consent and is mandatory. Context interpretation is handled conversationally by `$ewai-context-import`.
+
+`archaeology prepare-personas` snapshots the installed core, premium, personal, and project persona capability index into the bounded Archaeology bundle without exposing library paths. The AI completes its pass-by-pass value assessment and presents a concise recommended ensemble to the user. `archaeology validate-personas` is the hard gate before deep analysis; it requires completed reconnaissance, all analysis-pass assessments, a recorded user decision, valid persona references, and assignments for every selected persona.
+
+`archaeology validate` enforces the maximum-detail reconstruction contract, including the confirmed persona-routing gate. It rejects missing capability, coverage, reconstruction, persona-routing, or artefact manifests; missing SPECS record families; consolidated records that reuse a proposed path; placeholder-sized artefacts; unsupported completion states; and unjustified blocked or not-applicable entries.
+
+`archaeology validate-completion` is the final closeout gate. It verifies terminal review decisions, a complete curation ledger, accepted records present and hash-matched in canonical SPECS, and a recorded user choice or explicit decline after the three-route prospective-work offer. Run it before describing Archaeology as complete.
+
+`archaeology prepare-review` creates a review guide and pending decision ledger after maximum-detail validation passes. Every reconstruction record requires a terminal, accountable decision; corrections must be applied and acknowledged in the ledger. `archaeology curate` requires explicit consent, preflights every accepted record, refuses differing canonical SPECS conflicts, files only accepted proposals, and writes a provenance-preserving curation ledger.
+
+External validation is project-local. `init --claude --codex --antigravity`, discovery answers, `validation set`, and `validation checkpoint` update the same durable policy in `SPECS/pipeline.yaml`. Availability and enablement are separate; per-checkpoint settings control independent reviewers, bounded review/fix cycles, breadth, depth, and output size. `validation list --orchestrator <host>` shows the effective policy after excluding the active orchestrator. Standards compliance cannot be disabled or waived.
+
+`doctor` validates the project contract, required SPECS paths, persona registry, and configured repository paths.
+
+`intent create` accepts `--delivery-shape <json-or-yaml>` so the capture conversation can persist whether an intent should stay whole, split before delivery, or pause for owner decisions. `intent map-create` carries the same preview for every proposed child intent.
+
+`afk preflight` and `afk start` apply only after explicit Build approval and guarded entry into Build. The local conductor executes ready AFK task contracts on real branches in isolated worktrees, records its ignored runtime state under `.ewai-pipeline/afk/`, and leaves project-owned reports and evidence under `SPECS/6.Build/<slug>/tasks/`. Use the `$ewai-deliver` interaction rather than teaching these commands to the user. Repository topology comes from `SPECS/pipeline.yaml`: a task maps to its named repository, while the project-root repository owns canonical evidence. Per-repository integration branches may be declared in `task-graph.json.repository_branches`; start creates a missing integration branch from a clean current branch but does not silently switch to one that already exists. Status, safe pause, recovery/resume, and cancellation remain available by durable run ID.
+
+`checkin` starts or reuses the project-local loopback pipeline dashboard, refreshes its SQLite projection, and reports Mind Palace tidiness. `dashboard` and `server start` do the same explicitly; `server status` and `server stop` inspect or stop it. Agent hosts launch `mcp` over stdio from the project configuration created by `init`; it is not a persistent background server.
+
+The MCP surface includes Mind Palace search and tidiness, work-item listing and updates, phase and artefact registration, and active-work start/event/finish operations. These drive the Kanban, sprint, intent-detail, live-work, and Mind Palace views without requiring users to learn matching CLI commands.
+
+Mind Palace indexing is derived from canonical `SPECS/` files. `palace search` returns the best matching section from each document. `palace tidiness` is deterministic and read-only. `palace housekeeping` groups the findings but changes no files; use `$ewai-palace-housekeeping` for a Knowledge Curator-led review and explicit approval before editing canonical knowledge. A no-op is valid when the Palace is already tidy.
+
+## Pack and persona commands
+
+Human-readable check-in is compact by default. Use \`--verbose\` for expanded diagnostic text or \`--json\` for the complete structured contract. Brief presentation never omits mandatory blockers, standards or approval boundaries. Init and version checks use the CLI/metadata, not installed-source investigation or an unsupported \`ewai --version\` command.
+
+```bash
+ewai pack list [--json]
+ewai persona index [--project PATH] [--query TEXT] [--json]
+ewai persona list [--project PATH] [--query TEXT] [--json]
+ewai persona create SLUG [--scope personal|project] [--project PATH] [--name NAME] [--category CATEGORY] [--force] [--json]
+ewai persona path [--scope personal|project] [--project PATH] [--json]
+ewai persona premium configure [--project PATH] [--machine-name NAME] [--json]
+ewai persona premium status [--project PATH] [--json]
+ewai persona premium sync [--project PATH] --yes [--json]
+```
+
+`persona index` returns a compact local catalog of identifiers, descriptions, categories, tiers, tags, capabilities, and paths for contextual persona routing. Personal personas live in `~/.ewai/personas/` and can be reused across projects. Project personas live in `SPECS/1.Scope/personas/project/` and should be versioned with the project. Professional persona sources are opt-in packs and must not be assumed available merely because an entitlement mechanism is configured.
+
+The premium portion of `checkin` verifies access and compares versions without downloading. `persona premium configure` explains verify-and-install, accepts a website-purchased key in a hidden terminal prompt, stores it privately after verification and immediately downloads and installs through the core ZIP verifier. Its safe result confirms installed version/count or reports failure. Keys never enter arguments or SPECS. Later `persona premium sync` obtains a short-lived website grant, verifies ZIP/pack contents and atomically updates the managed pack at `~/.ewai/packs/ewai.personas.professional/`; `--yes` is explicit approval for that later download. Reading is neither setup nor sync consent. Source control is not a premium persona delivery route.

package/skills-src/ewai-pipeline/references/specs-contract.md

@@ -0,0 +1,16 @@
+# SPECS project contract
+
+`.ewai-pipeline/project.json` is the workspace locator. Its `specsRoot` points to the durable SPECS root, whose `pipeline.yaml` identifies repositories, enabled packs, the skill namespace, and approval requirements. The path is `SPECS` by default, but a multi-repository workspace should normally use a dedicated location such as `project-knowledge/SPECS`.
+
+Durable outputs use these roots:
+
+- `SPECS/1.Scope/`: project context, scope, domain language, research, and personas.
+- `SPECS/2.Purpose/intents/`: project intents.
+- `SPECS/3.Evidence/`: success evidence, archaeology, risks, gates, iteration logs, postmortems, and retrospectives.
+- `SPECS/4.Constraints/`: binding project boundaries.
+- `SPECS/5.Strategy/`: approach, stack, decisions, options, patterns, runbooks, and work capsules.
+- `SPECS/6.Build/<slug>/`: delivery trackers, plans, gates, test evidence, and retrospectives.
+
+Project-owned persona sources use `SPECS/1.Scope/personas/project/`; project-specific refinements use `SPECS/1.Scope/personas/overlays/`. Core personas come from EWAI, personal personas come from the user's `~/.ewai/personas/` library, and premium personas come from entitled packs. Personal and premium source files are not copied into project truth unless the user deliberately promotes a project-owned derivative.
+
+Do not treat `.ewai-pipeline/` as durable evidence. It may hold databases, indexes, caches, logs, and other rebuildable operational state.

package/skills-src/ewai-portfolio/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: ewai-portfolio
+description: Review an EWAI project portfolio or programme using the bounded read-only portfolio snapshot, explicit evidence classes, standard host-model reasoning, and contextually engaged installed personas. Use when Codex needs to examine portfolio hierarchy, project ownership, cross-project dependencies, stale or missing child evidence, programme attention, or the effect of installed core, project, personal, or premium persona lenses without changing child projects.
+---
+
+# EWAI Portfolio Review
+
+Resolve the project and configured SPECS root before acting. Read [the portfolio contract](references/portfolio-contract.md) before interpreting a workspace or producing advice.
+
+Use the standard host LLM or model for reasoning. The complete baseline combines the bounded snapshot, its explicit review questions, and installed project and core personas. Personal and premium personas are optional enrichment, not a prerequisite.
+
+## Retrieve the safe snapshot
+
+Validate the project-owned manifest first:
+
+```bash
+ewai portfolio validate --project . --json
+```
+
+Then retrieve the current workspace, using a concise focus when the user has named a concern:
+
+```bash
+ewai portfolio status --focus "delivery ownership and dependency risk" --project . --json
+```
+
+When the EWAI MCP server is available, `ewai_portfolio_status` with an optional `focus` is the equivalent read-only route. Do not send a repository root, user identity, approval or child content through either interface.
+
+Respect `not-configured`, `invalid`, `ready`, and `attention` exactly. Do not convert missing, stale, unavailable or disagreeing evidence into a healthy conclusion. If the focus changes materially, retrieve a fresh snapshot so the active ensemble can swap relevant personas in and out.
+
+## Disclose the active reasoning ensemble
+
+Before review, list every active persona with its name, tier, matched signals, and engagement reason. Use only the returned safe metadata and apply each lens within that stated reason.
+
+- Treat installed project and core personas as part of the baseline available to this project.
+- Use installed personal or premium personas only when the snapshot selects them as relevant.
+- Treat missing premium access as informative and nonblocking.
+- Do not run entitlement or library synchronisation commands, fetch premium content, reconstruct unavailable personas, or expose persona bodies.
+
+Personas challenge the evidence. They are not users, stakeholders, validators, approvers or sources of project truth.
+
+## Review in evidence order
+
+1. Report declared hierarchy, ownership and dependencies as `declared`.
+2. Report allowlisted child state and attention as `observed` or `declared-child-state`, preserving freshness and disagreement.
+3. Label model-derived relationships or consequences as `inferred`.
+4. Label persona concerns and alternative interpretations as `persona-hypothesis`.
+5. Reserve `human-decision` for an actual recorded decision by a named accountable human.
+6. Use the workspace review questions to examine exposed dependencies, missing evidence, the next owner decision, and unsupported conclusions.
+
+Never merge those classes into a score or an automatic portfolio verdict. The V1 workspace does not project observed cross-project Source Map edges; state that limitation rather than inventing them.
+
+## Produce an actionable review
+
+Return:
+
+1. the selected portfolio context and snapshot status;
+2. active persona names, tiers and reasons;
+3. declared facts;
+4. observed evidence, freshness and disagreements;
+5. explicitly labelled inferences and persona hypotheses;
+6. unresolved questions and the named owner or child project that can answer them; and
+7. the advisory and security assurance notices.
+
+Keep absolute paths, raw child documents, prompts, persona bodies, credentials and unrestricted file content out of the output.
+
+## Authority boundary
+
+This skill is advisory and read-only. It cannot edit the manifest, write child SPECS, dispatch work, approve Build or Manual QA, accept risk, certify security, change release readiness, deploy, or release. Route every unresolved decision to the named accountable human or child project.
+
+Stop if safe validation fails, evidence escapes the declared workspace, required fields are missing from the server contract, the user asks the review to mutate a child project, or a conclusion would require pretending persona/model output is human evidence.

package/skills-src/ewai-portfolio/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Portfolio"
+  short_description: "Review project and portfolio evidence safely"
+  default_prompt: "Use $ewai-portfolio to review this project portfolio with explicit evidence classes and active persona lenses."

package/skills-src/ewai-portfolio/references/portfolio-contract.md

@@ -0,0 +1,67 @@
+# Portfolio review contract
+
+Read this reference before interpreting `ewai.portfolio-workspace/v1`, troubleshooting a portfolio, or producing an LLM-assisted programme review.
+
+## Canonical inputs
+
+- `.ewai-pipeline/project.json` locates the host project and its configured SPECS root.
+- `SPECS/pipeline.yaml` owns configured repository names and safe workspace-relative roots.
+- `SPECS/1.Scope/portfolio.yaml` owns the portfolio, programme and project hierarchy plus declared project-to-project dependencies.
+- Each child project owns its own project config, intent metadata, delivery state, approvals and Manual QA evidence.
+
+The projection is disposable and read-only. It must never become a route for rewriting child evidence.
+
+## Workspace states
+
+| Status | Meaning | Safe response |
+| --- | --- | --- |
+| `not-configured` | No canonical portfolio manifest exists. | Point to the implementation guide; do not create one without authority. |
+| `invalid` | Schema, topology, configured root or path validation failed. | Report stable diagnostics and stop interpretation. |
+| `ready` | The manifest is valid and no current attention item was projected. | Review the evidence; do not call this approval or assurance. |
+| `attention` | One or more child evidence conditions need an owner. | Preserve each reason and route it to its named owner. |
+
+Member evidence may be `declared`, `ready`, `missing`, `stale`, `disagreement`, or `unavailable`. Absence never means healthy.
+
+## Safe public fields
+
+The workspace may expose:
+
+- safe member IDs, names, kinds, parent IDs, owners, configured repository names and relative project paths;
+- bounded intent counts and status metadata;
+- current child delivery phase/status, blocked reason, Build-approval boolean, Manual QA status, update time and safe relative evidence reference;
+- declared dependency ID, direction, rationale and owner;
+- stable attention code, member, owner, reason and evidence class;
+- active persona ID, name, tier, matched signals and engagement reason;
+- installed-tier availability counts, bounded review questions, evidence classes and mandatory notices.
+
+It must not expose absolute roots, raw intent or persona bodies, prompts, credentials, unrestricted child files, adapter entrypoints or request-supplied authority.
+
+## Evidence taxonomy
+
+| Class | Meaning | Authority |
+| --- | --- | --- |
+| `declared` | Portfolio structure or dependency recorded by the project. | A project declaration, not proof of runtime coupling. |
+| `observed` | Allowlisted evidence read from a child project. | Bounded observation with freshness and provenance. |
+| `inferred` | A consequence reasoned from declared and observed evidence. | A review proposition requiring confirmation. |
+| `persona-hypothesis` | A concern surfaced through an active persona lens. | Advisory question, never stakeholder fact. |
+| `human-decision` | A decision actually recorded by a named accountable person. | The only decision class; scope remains limited to the recorded authority. |
+
+`declared-child-state` identifies a child project’s own recorded delivery claim. Keep it distinct from independently observed cross-project coupling.
+
+V1 returns `observedEvidence.status: not-available` for cross-project Source Map dependencies. Do not reinterpret declared dependencies as observed edges.
+
+## Persona and LLM method
+
+`review.standardLlmAvailable` keeps ordinary host-model reasoning available. Installed project and core personas improve framing at baseline. Installed relevant personal or premium metadata can enrich the bounded ensemble.
+
+When focus changes, retrieve the snapshot again and replace the active ensemble. Do not retain stale lenses merely because they were useful in an earlier pass. Never require premium access, approximate an unavailable specialist, or initiate entitlement/library installation from a review.
+
+Persona output remains `persona-hypothesis` until supported by project evidence or resolved by a named person. It cannot create `human-decision` evidence.
+
+## Human and assurance boundary
+
+Always preserve both notices returned by the workspace. The security notice begins:
+
+> Security validation is evidence, not certification or proof that this system is secure.
+
+Portfolio analysis cannot approve Build or Manual QA, accept residual risk, certify security, mutate child SPECS, change release readiness, dispatch work, deploy or release. Route the next action to the member or dependency owner shown in the projection.

package/skills-src/ewai-project-discovery/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: ewai-project-discovery
+description: Interview a project owner after EWAI initialization, capture the project's purpose, users, outcomes, boundaries, technology direction, data and assurance profile, then generate the initial project-local SPECS brief, standards, compliance triage, and stack strategy. Use when starting, onboarding, re-profiling, or selecting a technology stack for an EWAI project before creating delivery intents or application code.
+---
+
+# EWAI Project Discovery
+
+Build shared understanding before planning or implementation. Treat generated recommendations as drafts for accountable human review.
+
+Resolve the workspace and SPECS root from `.ewai-pipeline/project.json`; all logical `SPECS/...` paths below are relative to that configured root.
+
+## Brief an existing project before Archaeology
+
+For an existing codebase, begin with a short conversational briefing before deep repository analysis. Ask one question at a time and establish:
+
+- why the project exists and why it matters now;
+- primary users and stakeholders;
+- desired outcomes and signs of failure;
+- business and operational context;
+- known constraints, non-goals, and behaviour that may be accidental or obsolete.
+
+Record the confirmed briefing at `SPECS/2.Purpose/explorations/project-brief.md`. Separate the user's account from repository-derived hypotheses. Offer `$ewai-context-import` for any folder of emails, meeting transcripts, documentation, research, requirements, or other project material. Use reviewed imported findings to make the remaining interview more specific. For an existing codebase, then hand off to `$ewai-archaeology`, which must compare its reconnaissance with the briefing and imported evidence and ask the owner to resolve material differences before deeper reconstruction.
+
+Do not launch the terminal-based discovery questionnaire inside an AI conversation. Conduct the interview naturally, prepare a repeatable answers file under the disposable `.ewai-pipeline/runtime/` boundary, and use the non-interactive `--answers` interface when generating the full Project SPECS after reviewed Archaeology evidence is available.
+
+## Run discovery
+
+1. Read the configured `pipeline.yaml`, the human project briefing, reviewed Context Import and Archaeology findings when present, and repository evidence for the existing stack.
+2. Run `ewai doctor --project <path>` and resolve failed project-contract checks.
+3. Run `ewai discover --project <path>`.
+4. Ask one interview question at a time. Prefer reviewed Context Import, Archaeology, repository, or SPECS evidence over asking the owner to rediscover a known fact.
+5. Keep unknown answers explicit. Do not convert uncertainty into an assumed requirement.
+6. Ask whether Claude CLI, Codex CLI, and Google Antigravity through the `agy` CLI are available for external validation; default each to unavailable unless the user explicitly confirms it. Availability does not force use: record whether each provider is enabled.
+7. Confirm the review-and-fix cycle limit, breadth, analysis depth, and output size for implementation-plan, test-plan, and post-code validation. Explain the token/assurance trade-off in human terms.
+8. Review the generated Project SPECS, technology stack, standards options, and compliance risk with their accountable owners.
+
+## Optional organisation policy baseline
+
+During Guided Setup, explain that an Organisation Policy Design Gate is optional. When the selected Organisation Blueprint contains policy contributions, show the resolved baseline, sources, rule and role counts, outcomes, pack pins, and exact effective digest. Use `$ewai-organisation-policy` to review the proposal and require a named person to approve that exact digest before materialisation. With no contribution or no approval, preserve the explicit non-blocking `not-configured` state.
+
+Do not infer policy from generic governance documents, make premium personas mandatory, or describe the baseline as production enforcement or compliance certification.
+
+## Select reproducible discovery depth
+
+Use `$ewai-evidence-depth` when onboarding an existing repository, repeating Discovery across participants or model sessions, or when assurance and context cost need an explicit trade-off. Refresh the Source Map, then prepare independent architecture, data, security, product, delivery, governance, and operations recommendations from repository coverage and attributed owner evidence.
+
+Show which core, project, personal, and optional installed premium personas are active for the current concern and why. Swap them as the concern changes. Persona advice never substitutes for the owner's account, confirms an inferred fact, or selects depth.
+
+Require a named review across all seven dimensions and keep stable gaps separate from how they are later grouped into intents or work. If Discovery is repeated, compare stored run fingerprints before attributing differences to the model. Treat unexplained coverage or gap variance as a reproducibility failure, and restore missing evidence context before proceeding.
+
+This is a local evidence workflow. It does not send feedback, run production code, enforce policy at runtime, install premium personas, or grant Build authority.
+
+## Select technology for a new project
+
+When no implementation repository exists, do not ask the user to name a framework before understanding the project. First establish the product shape, deployment environment, team capability, data sensitivity, integrations, scale, availability, accessibility, compliance, budget, and operational ownership.
+
+Then:
+
+1. explain the material decision criteria in plain language;
+2. recommend fitting installed technology or stack packs, with trade-offs;
+3. let the user select a pack, record custom technology, or explicitly remain undecided;
+4. capture the decision and rationale in `SPECS/5.Strategy/architecture/stack.md`;
+5. route accepted minimum practices into project constraints, patterns, and ADRs rather than leaving them only as suggestions.
+
+If a stack choice is still uncertain and materially blocks an intent, create a bounded technical-spike intent through `$ewai-intent`. Do not select a stack merely because EWAI has a pack for it.
+
+After purpose and the material technology direction are understood, offer `$ewai-architecture` when the solution has consequential boundaries, integrations, data ownership, security or trust decisions, operational requirements, transition concerns, or enterprise dependencies. Discovery establishes enough context to start that conversation; it does not silently invent a complete architecture. Accepted Architecture proposals then become the project standards, patterns, ADRs, risks, diagrams, and strategy that delivery must honour.
+
+For a repeatable or non-interactive interview, copy and complete `templates/discovery-answers.yaml` from the EWAI installation, then run:
+
+```bash
+ewai discover --project <path> --answers <answers.yaml>
+```
+
+## Decision discipline
+
+- Select installed technology or stack pack identifiers when they fit.
+- Treat pack commands as a starting point, not a complete framework best-practice standard. Only claim practices that are present in the selected pack or accepted project SPECS.
+- Record custom or undecided technology rather than forcing the nearest pack.
+- Treat detected frameworks as evidence, not automatic approval of a stack.
+- Require provenance, licence, compatibility, and support review before recommending boilerplate.
+- Label compliance results as candidate reviews. Never claim legal advice, certification, or compliance from interview answers.
+- Allow only providers marked both `available` and `enabled` in `SPECS/pipeline.yaml` to satisfy external-validation stages.
+- Exclude the active orchestrator from independent validation. A one-system project therefore records external stages as not-supported rather than pretending self-review is independent.
+- Treat external review cycles as configurable assurance. Treat standards compliance as mandatory and non-waivable.
+- Keep unsupported stages visible and never mark them passed.
+- Keep `SPECS/` as durable truth and `.ewai-pipeline/` as regenerable runtime state.
+
+## Completion boundary
+
+Discovery is complete when the project owner has a reviewable purpose and scope, the technical owner has a stack decision or explicit open decision, and assurance owners can see every triggered review and unknown.
+
+Do not begin Build. Create or enrich the first delivery intent only after the discovery artefacts have been reviewed.
+
+Read [discovery contract](references/discovery-contract.md) when validating outputs or automating answers.

package/skills-src/ewai-project-discovery/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "EWAI Project Discovery"
+  short_description: "Interview and profile a new EWAI project"
+  default_prompt: "Use $ewai-project-discovery to interview me about this project and create its initial SPECS profile."