@surlymochan/evalid 0.0.0-stage → 0.4.1

package/docs/superpowers-comparison.md

@@ -0,0 +1,82 @@
+# Superpowers Comparison
+
+Use this page when someone asks whether xflow should exist if Superpowers-style
+agent skills already cover planning, TDD, debugging, review, and branch
+finishing.
+
+## Verdict
+
+Superpowers is excellent as an agent-behavior methodology. It is lightweight,
+portable, and good at making the model behave like a careful engineer.
+
+xflow is better when the claim must survive outside one conversation: executable
+workflow data, repo-local state, machine-readable proof, cross-tool handoff, and
+launch readiness gates.
+
+```text
+Superpowers = behavior discipline
+xflow = workflow runtime plus audit evidence
+```
+
+## Scorecard
+
+Overall, xflow wins for repo-local team delivery and public launch scrutiny:
+`91/100` versus `78/100`. Superpowers still wins on overall lightweight feel,
+but xflow now ties it on explicit behavior-discipline coverage.
+
+| Dimension | Weight | Superpowers | xflow | Winner |
+| --- | ---: | ---: | ---: | --- |
+| Agent behavior shaping | 15 | 15 | 15 | Tie |
+| TDD and debugging discipline | 15 | 14 | 15 | xflow |
+| Repo-local evidence | 20 | 9 | 19 | xflow |
+| Cross-tool handoff | 15 | 10 | 14 | xflow |
+| Workflow execution | 20 | 12 | 18 | xflow |
+| Launch readiness | 15 | 6 | 10 | xflow |
+
+The scores are deliberately evidence-linked rather than vibe-only. The
+machine-readable scorecard includes `evidence_refs` per dimension, pointing to
+surfaces such as `xflow coach bugfix`, `xflow coach tdd`, `xflow coach debug`, `xflow coach red`, `xflow coach green`, `xflow coach verify`, `xflow coach qa`, `xflow coach ship`, `workflows/yolo.yaml`,
+`workflows/corps.yaml`, `test/tdd-proof.test.js`, `xflow goal audit --json`,
+`xflow launch audit --json`, and `npm run release:pack`.
+
+Machine-readable form:
+
+```bash
+xflow compare superpowers --json
+```
+
+## When Superpowers Wins
+
+- A developer wants lightweight behavior coaching without adopting a workflow
+  runtime.
+- The task is a normal code change where planning, TDD, debugging, and review
+  prompts are enough.
+- The team values minimal setup over durable repo evidence.
+
+## When xflow Wins
+
+- The work needs a persistent project goal, not only thread-local intent.
+- A reviewer needs proof artifacts, not only a well-written final answer.
+- A team wants yolo/corps tracks, archive ordering, handoff, and launch gates.
+- The team wants named coaching entrypoints such as `xflow coach bugfix`,
+  `xflow coach feature`, `xflow coach review`, `xflow coach tdd`,
+  `xflow coach debug`, `xflow coach red`, `xflow coach green`,
+  `xflow coach verify`, `xflow coach qa`, and
+  `xflow coach ship`.
+- A public launch claim must be backed by commands such as:
+
+```bash
+xflow compare superpowers --json
+xflow launch dossier
+xflow score --json
+xflow workflow validate yolo
+xflow workflow validate corps
+npm run release:pack
+```
+
+## Objective Judgment
+
+xflow should not claim that Superpowers is obsolete. Superpowers remains better
+for low-friction model behavior shaping. xflow's stronger claim is narrower and
+more defensible: it turns that discipline into repo-owned workflow evidence
+that survives handoff, review, release, and public launch scrutiny.

package/docs/team-adoption.md

@@ -0,0 +1,123 @@
+# Team Adoption Operating Model
+
+Use this page when adopting evalid in a team rather than a solo local workflow.
+The goal is a stable operating contract: every change has one workflow track, one
+proof path, one review surface, and one release boundary.
+
+## Readiness Levels
+
+| Level | Audience | Required Proof |
+| --- | --- | --- |
+| Pilot | one maintainer, one repository | `xflow doctor`, `xflow workflow validate yolo`, `npm run drift:scan` |
+| Team | 2-8 contributors | PR template requires workflow track, proof artifact, reviewer checklist, and drift evidence |
+| Organization | multiple repositories | CI runs adoption smoke, release pack, skill diff, and score checks before publishing claims |
+
+Do not present a repository as team-ready until the Team level is green.
+Do not present a package as publicly promoted until the Organization level is green.
+
+## Role Model
+
+| Role | Responsibility |
+| --- | --- |
+| Operator | chooses `yolo` or `corps`, starts the workflow, and keeps `HANDOFF.md` current |
+| Implementer | makes code/doc changes inside the accepted proposal and plan |
+| Reviewer | checks proof artifacts, drift scan, TDD semantics, and archive order |
+| Release owner | runs `npm run release:pack`, `npm run publish:check`, and confirms package ownership |
+
+The conversation LLM is not the release owner. It can execute commands and collect
+evidence, but a human owner accepts public publication.
+
+## Track Policy
+
+Use `yolo` when the current conversation or a human implementer owns the work:
+
+```bash
+xflow workflow run yolo --project-root . \
+  --title "<change title>" \
+  --change-type backend \
+  --tdd-red-command "<failing command>" \
+  --tdd-green-command "<passing command>"
+```
+
+Use `corps` when the workflow runtime should own heavy product/design execution:
+
+```bash
+xflow serve &
+xflow corps --project-root . \
+  --title "<product change>" \
+  --change-type frontend \
+  --change-id <id> \
+  --competitor-product <name> \
+  --target-surfaces primary_workspace \
+  --primary-reference-surface primary_workspace \
+  --reference-scenarios-json '<json>'
+xflow proof --track corps --change-id <id> --project-root .
+```
+
+`corps` completion is not accepted from screenshots, chat summaries, partial
+artifact checks, shortened workflow YAML, or stubbed agent output. It is
+accepted only when `corps_proof.json` reports `ok=true` with strict runtime
+evidence: built-in corps manifest, hash-linked execution logs, every canonical
+phase completed, every atom/gate witnessed, and no `stub` / `task_queued` /
+`pencil_stubbed` fallback.
+
+## Required CI Checks
+
+Every team repository using evalid should keep an equivalent CI boundary:
+
+```bash
+npm test
+npm run drift:scan
+npm run skill:diff
+npm run release:pack
+xflow score --json
+xflow workflow validate yolo --project-root .
+xflow workflow validate corps --project-root .
+```
+
+For consumer projects that only install the CLI, keep a smaller adoption smoke:
+
+```bash
+npm install -g @surlymochan/evalid
+xflow guide
+xflow init --project-root .
+xflow doctor --project-root .
+xflow workflow validate yolo --project-root .
+```
+
+## PR Acceptance Checklist
+
+A reviewer can accept a workflow-driven PR only when all of these are true:
+
+- The PR names the track: `yolo` or `corps`.
+- `proposal.md` and `plan.md` match the code and documentation changes.
+- `verify_proof.json` or `corps_proof.json` is present for the claimed track.
+- TDD proof includes red, green, and quality artifacts when code changed.
+- `npm run drift:scan` passed after workflow, skill, or public-doc changes.
+- Archive order remains `A5.archive.commit_push_close` before `A6.pr.create`.
+- `HANDOFF.md` names the current stage, risk, and next operator action.
+
+## Failure Policy
+
+- If `status.json` disagrees with proof artifacts, trust proof artifacts and fix
+  state persistence before claiming completion.
+- If `skill:diff` fails, run `npm run skill:sync` intentionally, then rerun
+  `npm run skill:diff`; do not publish with installed-skill drift.
+- If `corps` lacks benchmark evidence or a primary reference surface, stop at
+  the governed entry contract instead of inventing a product-specific shortcut.
+- If release pack passes but publish dry-run fails, treat the package as locally
+  ready but not publicly publishable.
+
+## 95 Percent Readiness Gate
+
+For public promotion, the project should satisfy all of these:
+
+- `xflow score --json` returns `ok=true` and every dimension is `strong`.
+- `npm run release:pack` passes from a clean source checkout.
+- CI includes the minimal external adoption example.
+- The reviewer guide and this team adoption model are linked from README.
+- `yolo` dry-run exposes the full lite workflow without HTTP or Pencil.
+- `corps` dry-run exposes a governed proof contract with no entry issues when
+  benchmark evidence and `primary_reference_surface` are supplied.
+- Remaining limitations are operational, not architectural: external service
+  auth, package ownership, and real-case visual quality variance.

package/docs/tooling-matrix.md

@@ -0,0 +1,91 @@
+# evalid Tooling Matrix
+
+Use this page when installing or explaining xflow across different agent tools.
+
+The rule is simple: keep the workflow runtime in the project and keep the agent-specific layer thin. Tools can change; workflow YAML, TDD proof, handoff state, and archive gates should stay the same.
+
+## Universal CLI Contract
+
+Every supported tool should be able to run this sequence:
+
+```bash
+npm install -g @surlymochan/evalid
+xflow quickstart
+xflow guide
+xflow assess
+xflow demo launch
+xflow launch dossier
+xflow compare codex-goal
+xflow compare superpowers
+xflow compare super-assistant
+xflow compare gstack
+xflow init --project-root .
+xflow goal set "Ship the next verified change" --project-root .
+xflow goal audit --project-root . --json
+xflow doctor --project-root .
+xflow workflow validate yolo --project-root .
+```
+
+For source checkouts, replace the global install with:
+
+```bash
+npm install
+npm run release:pack
+```
+
+Keep release-owner checks out of universal first-run docs. `xflow adoption
+validate --json`, `xflow package preflight --check-registry --check-auth
+--json`, and `xflow package audit --check-registry --json` are still required
+for launch, but they intentionally fail until real adoption or npm registry
+evidence exists.
+
+## Tool Matrix
+
+| Tool | Install / Enable | First Command | Notes |
+| --- | --- | --- | --- |
+| Codex CLI / App | Install package or use source checkout | `xflow guide` | Best paired with `xflow:takein`, `xflow:goal`, `xflow:plan`, and `xflow:yolo` skills. |
+| Claude Code | Install package in the project shell | `xflow doctor --project-root .` | Keep workflow prose out of CLAUDE.md; point Claude at this CLI contract. |
+| Cursor | Add project rule pointing to this page | `xflow workflow validate yolo --project-root .` | Use `.as-xflow/config.json` for stable aliases instead of duplicating commands in rules. |
+| OpenCode | Use plain shell commands | `xflow init --project-root .` | Keep verification in package scripts so OpenCode tasks run the same gates. |
+| Gemini CLI | Use package install or source checkout | `xflow guide` | Treat xflow as the local runtime; use Gemini for execution, not workflow source-of-truth. |
+| Generic CLI Agent | Any shell with Node 22+ | `xflow assess --json` | Use JSON output when the agent needs machine-readable quality and readiness context. |
+
+## Skill Entry Points
+
+Think of the skill family as a ladder, not a menu. Start with a durable goal,
+reload context, plan once, then choose the light or heavy execution track.
+
+| Skill | Purpose |
+| --- | --- |
+| `xflow:takein` | Reload current repo context from `HANDOFF.md` and local state. |
+| `xflow:goal` | Set, inspect, or audit `.xflow/GOAL.md` as the project direction anchor; CLI users can run `xflow goal set` and `xflow goal audit`. |
+| `xflow:plan` | Produce `plan.md`; do not choose yolo vs corps. |
+| `xflow:ralph` | Keep a concrete task moving through implementation, verification, review feedback, and self-healing repair. |
+| `xflow:yolo` | Run the lite delivery path against an existing plan. |
+| `xflow:corps` | Run heavy product/multi-agent delivery through `xflow corps`, then verify `corps_proof.json`. |
+| `xflow:handoff` | Refresh durable project handoff. |
+| `xflow:aha` | Persist durable lessons into `AHA.md`. |
+
+## Non-Negotiable Invariants
+
+- `.xflow/GOAL.md` is stronger than a thread-only Codex goal only when every
+  delivery entry reads it as direction context and reports alignment.
+- `xflow:plan` is plan-only and track-neutral.
+- `yolo` and `corps` reuse the current plan.
+- TDD runs as `tdd-red -> execute -> tdd-green`.
+- `I6c.tdd.quality_review` must run after green proof.
+- `A5.archive.commit_push_close` publishes before `A6.pr.create`.
+- `xmem` remains outside the xflow namespace.
+
+## Copy-Paste Setup Snippet
+
+Use this in project-level agent instructions:
+
+```text
+Use evalid as the workflow source of truth. Start with `xflow guide`, then run
+`xflow goal set "<project direction>" --project-root .`, `xflow doctor --project-root .`,
+`xflow goal audit --project-root . --json`, and `xflow workflow validate yolo --project-root .`.
+For implementation, use `xflow:plan` first, then `xflow:yolo` or `xflow:corps`
+without re-planning. Preserve the split TDD order: tdd-red before execute,
+tdd-green after execute, with I6c quality proof.
+```

package/docs/walkthrough.md

@@ -0,0 +1,76 @@
+# Walkthrough
+
+This walkthrough is the public demo script for evaluating xflow without reading the implementation.
+
+## 1. Install Or Use Source
+
+Global package path after publish:
+
+```bash
+npm install -g @surlymochan/evalid
+```
+
+Source checkout path:
+
+```bash
+git clone <repo-url> evalid
+cd evalid
+npm install
+```
+
+## 2. Initialize A Clean Project
+
+```bash
+xflow guide
+xflow init --project-root .
+xflow doctor --project-root .
+xflow workflow validate yolo --project-root .
+```
+
+## 3. Run A Spec Check
+
+```bash
+xflow adapter import-file --project-root . --input docs/fixtures/tracker-item.json --json
+xflow spec delta --project-root . --change-id <change-id>
+```
+
+Expected output:
+
+```text
+specs/changes/<change-id>/spec_delta_review.json
+specs/changes/<change-id>/spec_delta_review.md
+```
+
+## 4. Compare Against Reference Systems
+
+```bash
+xflow compare superpowers
+xflow compare super-assistant
+xflow compare codex-goal
+xflow compare openspec
+xflow compare gstack
+xflow compare spec-kit
+xflow score
+```
+
+## 5. Prove Release Readiness
+
+```bash
+npm run release:pack
+npm run publish:check
+```
+
+## What The Demo Proves
+
+- xflow can initialize without copying internal workflow files into the consumer project
+- workflow data validates before execution
+- spec delta review is an artifact, not just prose
+- external tracker context can enter xflow through a thin adapter while repo-local artifacts own workflow truth
+- TDD proof and test-quality gates are part of the delivery loop
+- release packaging is checked before public claims
+
+## What The Demo Does Not Prove
+
+- npm ownership, until the real package is published
+- deep bidirectional integration maturity for every tracker, beyond the generic import-file and GitHub issue adapters
+- semantic superiority over every spec-kit extension, until the benchmark uses the same brownfield feature