@williambeto/ai-workflow 1.18.9 → 1.18.10

package/README.md

@@ -166,7 +166,7 @@ See [`docs/setup-codex-opencode.md`](docs/setup-codex-opencode.md) for installat
 | `@williambeto/ai-workflow` CLI | Preview |
 | Stack variants and examples | Reference — adapt to the target project |
 
-Suitable for **private preview** with developers who accept validation-first workflow assets and can report rough edges. Not ready for broad public announcement until the final public-readiness audit confirms no high-severity blockers remain.
+Suitable for developers and teams who want validation-first AI workflow assets and accept that the CLI, OpenCode integration, and stack variants are still evolving. Use GitHub issues for questions, bugs, and improvement proposals.
 
 ## Current limitations
 
@@ -176,6 +176,8 @@ Suitable for **private preview** with developers who accept validation-first wor
 
 See [`ROADMAP.md`](ROADMAP.md) for planned improvements.
 
+Before changing repository visibility or making a major public-facing release, use [`runbooks/publication-readiness-checklist.md`](runbooks/publication-readiness-checklist.md).
+
 ## Start now
 
 1. Pick one small feature.

package/checklists/change-spec-readiness-checklist.md

@@ -0,0 +1,34 @@
+# Change Spec Readiness Checklist
+
+Use this checklist before implementation starts.
+
+## Clarity and scope
+
+- [ ] Objective is clear and measurable.
+- [ ] Problem is explicit.
+- [ ] Scope and out-of-scope are explicit.
+- [ ] Assumptions are explicit and labeled.
+- [ ] Open questions are resolved or marked as blockers.
+
+## Behavior and design
+
+- [ ] Requirements are testable.
+- [ ] Scenarios cover main flow and key edge cases.
+- [ ] Technical design is lightweight and sufficient for implementation.
+- [ ] Constraints and integration points are explicit.
+
+## Delivery readiness
+
+- [ ] Task breakdown is small, ordered, and reviewable.
+- [ ] Validation plan includes real commands/checks.
+- [ ] Expected evidence is explicit.
+- [ ] Risks include mitigation notes.
+
+## Decision
+
+Mark one:
+
+- [ ] Ready for implementation handoff
+- [ ] Needs clarification
+- [ ] Too broad (split into smaller changes)
+- [ ] Blocked by missing context/decision

package/docs/full-documentation.md

@@ -203,10 +203,18 @@ Spec-Driven commands:
 
 | Command | Purpose |
 | --- | --- |
+| [`opencode/commands/specs/create-spec-from-request.md`](opencode/commands/specs/create-spec-from-request.md) | Turn a vague request into a lightweight change artifact before coding. |
 | [`opencode/commands/specs/create-spec-from-requirement.md`](opencode/commands/specs/create-spec-from-requirement.md) | Draft a testable spec from an approved requirement. |
 | [`opencode/commands/specs/review-spec.md`](opencode/commands/specs/review-spec.md) | Review spec readiness before technical planning. |
 | [`opencode/commands/specs/spec-to-technical-plan.md`](opencode/commands/specs/spec-to-technical-plan.md) | Convert an approved spec into technical planning output. |
 | [`opencode/commands/specs/spec-to-pr-breakdown.md`](opencode/commands/specs/spec-to-pr-breakdown.md) | Split an approved spec into small, reviewable PRs. |
+| [`opencode/commands/specs/spec-to-tasks.md`](opencode/commands/specs/spec-to-tasks.md) | Convert approved spec into small implementation tasks with validation and evidence. |
+
+Consumer-project artifact path convention for lightweight specs:
+
+```txt
+docs/specs/[spec-type]/[yyyy-mm-dd]-[change-slug]/
+```
 
 ## OpenCode agent model
 
@@ -215,6 +223,7 @@ OpenCode agents are operational roles. Skills are reusable capabilities. Command
 | Agent | Role |
 | --- | --- |
 | [`discovery`](opencode/agents/discovery.md) | Explore project context before planning. |
+| [`spec-engineer`](opencode/agents/spec-engineer.md) | Convert vague requests into lightweight spec-driven change artifacts before coding. |
 | [`planner`](opencode/agents/planner.md) | Convert objectives into requirements, specs, plans, and PR breakdowns. |
 | [`orchestrator`](opencode/agents/orchestrator.md) | Route multi-step work across gates and specialists. |
 | [`implementer`](opencode/agents/implementer.md) | Implement scoped changes. |
@@ -314,6 +323,7 @@ Templates are reusable starting points, not completed project documents.
 | [`templates/README.template.md`](templates/README.template.md) | Base project README. |
 | [`templates/REQUIREMENT.template.md`](templates/REQUIREMENT.template.md) | Product requirement. |
 | [`templates/SPEC.template.md`](templates/SPEC.template.md) | Functional specification. |
+| [`templates/change-proposal.template.md`](templates/change-proposal.template.md) | Lightweight change proposal/spec artifact. |
 | [`templates/TECH-PLAN.template.md`](templates/TECH-PLAN.template.md) | Technical plan. |
 | [`templates/PR-PLAN.template.md`](templates/PR-PLAN.template.md) | PR plan. |
 
@@ -329,6 +339,7 @@ Runbooks are operational guides for applying the workflow.
 | [`runbooks/validate-starter-in-real-project.md`](runbooks/validate-starter-in-real-project.md) | Prove adoption in a real project. |
 | [`runbooks/how-to-use-skills.md`](runbooks/how-to-use-skills.md) | Choose specialist skills. |
 | [`runbooks/commands-cheatsheet.md`](runbooks/commands-cheatsheet.md) | Choose Codex/OpenCode commands. |
+| [`runbooks/spec-driven-development.md`](runbooks/spec-driven-development.md) | Run lightweight spec-first flow and artifact conventions before implementation. |
 | [`runbooks/agent-delegation-workflow.md`](runbooks/agent-delegation-workflow.md) | Use orchestrator and handoff routing. |
 | [`runbooks/use-linear-for-operational-planning.md`](runbooks/use-linear-for-operational-planning.md) | Use Linear as the operational backlog when the roadmap is too large for daily planning. |
 | [`runbooks/validation-checklist.md`](runbooks/validation-checklist.md) | Validate docs, code, PRs, builds, security, accessibility, and deploy readiness. |

package/opencode/agents/README.md

@@ -17,7 +17,13 @@ Do not treat generic skills as OpenCode agents. A skill explains how to perform
 Client/request discovery:
 
 ```txt
-discovery → planner
+discovery → spec-engineer → planner
+```
+
+Lightweight spec-first delivery:
+
+```txt
+request → spec-engineer → implementer
 ```
 
 Feature delivery:
@@ -94,6 +100,7 @@ Do not use Napkin as a temporary task log, and never store secrets.
 | Agent | Purpose | Use when | Should not do |
 | ----- | ------- | -------- | ------------- |
 | `discovery` | Turn vague requests into a discovery brief. | Scope, risks, dependencies, and unknowns are unclear. | Estimate price, implement, edit files, perform execution/delegation routing directly (must return `Blocked` and route to `orchestrator`). |
+| `spec-engineer` | Turn vague/risky requests into lightweight change artifacts for implementation handoff. | Request ambiguity is high and team needs explicit agreement before coding. | Implement production code or create heavyweight process for tiny tasks. |
 | `planner` | Turn approved scope into requirements, specs, technical plans, and PR breakdowns. | Scope is approved and implementation needs a handoff. | Implement. |
 | `implementer` | Implement one selected PR. | A PR plan or handoff exists. | Expand scope or do opportunistic refactors. |
 | `fixer` | Diagnose and fix bugs, regressions, failures, and warnings. | There is broken behavior or failed validation. | Rewrite large areas without evidence. |

package/opencode/agents/spec-engineer.md

@@ -0,0 +1,85 @@
+# Spec-Engineer Agent
+
+## Role
+
+Turn vague, risky, or high-impact requests into lightweight change artifacts that are ready for implementation handoff.
+
+## Use when
+
+- A request is unclear, broad, or ambiguous.
+- The change can affect behavior, architecture, integration, or validation strategy.
+- The team needs explicit agreement on what to build before coding.
+
+## Do not use when
+
+- The task is a tiny docs-only or wording fix.
+- The scope is already fully specified and reviewed.
+
+## Required context
+
+- User request or discovery brief.
+- Repository rules from `AGENTS.md`.
+- Existing spec assets in `templates/`, `checklists/`, and `opencode/commands/specs/`.
+
+## Input discipline
+
+- Use `minimal-context` behavior: read only files needed for the active request.
+- Use `grep`/`glob` before reading large files.
+- Keep outputs compact and implementation-handoff ready.
+
+## Responsibilities
+
+- Receive vague requests and classify whether a spec is needed.
+- Define spec depth level (`tiny` | `standard` | `deep`) based on risk/impact.
+- Generate specification/change artifact before implementation.
+- Set spec status explicitly.
+- Expose assumptions and blocking questions.
+- Define scope and out-of-scope explicitly.
+- Produce requirements, scenarios, and acceptance criteria.
+- Identify edge cases, constraints, and risks.
+- Propose lightweight technical design.
+- Break work into small implementation tasks.
+- Define validation criteria and expected evidence.
+- Request review when uncertainty or risk is non-trivial.
+- Hand off to `implementer` (or `planner` when PR planning is still needed).
+
+## Constraints
+
+- Do not implement production code.
+- Do not refactor unrelated files.
+- Do not approve unresolved assumptions as facts.
+- Do not skip validation criteria or expected evidence.
+- Do not create heavyweight process for trivial work.
+
+## Required workflow
+
+```txt
+1) Receive vague request
+2) Classify if spec is needed
+3) Define spec depth level
+4) Generate specification artifact
+5) Define spec status
+6) Expose assumptions and blocking questions
+7) Define scope and out-of-scope
+8) Define requirements and scenarios
+9) Define acceptance criteria
+10) Define technical constraints and risks
+11) Create small implementation tasks
+12) Define validation and expected evidence
+13) Request review when needed
+14) Generate implementation handoff
+```
+
+## Expected output
+
+- Change artifact using `templates/change-proposal.template.md`
+- Default artifact location in consumer project: `docs/specs/<spec-type>/<yyyy-mm-dd>-<change-slug>/`
+- Spec depth level: `tiny` | `standard` | `deep`
+- Spec status: `Draft` | `In review` | `Ready for implementation handoff` | `Needs clarification` | `Too broad` | `Blocked`
+- Assumptions and blocking questions (if any)
+- Recommended next owner: `implementer` or `planner`
+
+## Stop conditions
+
+- Stop when the change artifact is explicit, testable, and handoff-ready.
+- Stop and mark `Blocked` if missing decisions make implementation unsafe.

package/opencode/commands/README.md

@@ -25,10 +25,12 @@ Adapt file names, command registration, or invocation style to your OpenCode set
 
 | File | Use when |
 | ---- | -------- |
+| `create-spec-from-request.md` | Turn a vague request into a lightweight change artifact before coding. |
 | `create-spec-from-requirement.md` | Draft a testable spec from an approved requirement. |
 | `review-spec.md` | Review spec readiness before technical planning. |
 | `spec-to-technical-plan.md` | Convert approved spec into technical planning output. |
 | `spec-to-pr-breakdown.md` | Split approved spec into small PRs. |
+| `spec-to-tasks.md` | Convert approved spec into small implementation tasks with validation and evidence expectations. |
 
 ## Usage Notes
 

package/opencode/commands/specs/create-spec-from-request.md

@@ -0,0 +1,27 @@
+# OpenCode Command - Create Spec From Request
+
+## Purpose
+
+Turn a vague request into a lightweight, implementation-ready change artifact.
+
+## Constraints
+
+1. Do not implement.
+2. Ask only necessary blocking questions (max 2 by default).
+3. Keep scope and out-of-scope explicit.
+4. Preserve existing behavior unless change is explicitly requested.
+
+## Context To Read
+
+- `templates/change-proposal.template.md`
+- `checklists/change-spec-readiness-checklist.md`
+- `AGENTS.md`
+
+## Expected Output
+
+- Draft change artifact using `templates/change-proposal.template.md`
+- Suggested output path in consumer project: `docs/specs/<spec-type>/<yyyy-mm-dd>-<change-slug>/00-proposal.md`
+- Assumptions
+- Open questions
+- Readiness: `Ready for implementation handoff` | `Needs clarification` | `Too broad` | `Blocked`
+- Recommended next owner: `implementer` | `planner`

package/opencode/commands/specs/review-spec.md

@@ -2,12 +2,14 @@
 
 ## Purpose
 
-Assess whether a spec is ready for technical planning.
+Assess and improve whether a spec/change artifact is ready for implementation handoff.
 
 ## Context To Read
 
 - `templates/SPEC.template.md`
+- `templates/change-proposal.template.md`
 - `checklists/spec-readiness-checklist.md`
+- `checklists/change-spec-readiness-checklist.md`
 - `AGENTS.md`
 
 ## Constraints
@@ -18,7 +20,7 @@ Assess whether a spec is ready for technical planning.
 
 ## Expected Output
 
-- Decision: `Ready` | `Needs clarification` | `Too broad` | `Blocked`
+- Decision: `Ready for implementation handoff` | `Needs clarification` | `Too broad` | `Blocked`
 - Findings by severity (`High`/`Medium`/`Low`)
 - Smallest safe fixes
 - Evidence references

package/opencode/commands/specs/spec-to-tasks.md

@@ -0,0 +1,26 @@
+# OpenCode Command - Spec To Tasks
+
+## Purpose
+
+Convert an approved spec/change artifact into small, reviewable implementation tasks with validation and evidence expectations.
+
+## Constraints
+
+1. Do not implement.
+2. Keep tasks ordered and dependency-aware.
+3. Keep each task objective small and testable.
+4. Include validation criteria and expected evidence.
+
+## Context To Read
+
+- `templates/change-proposal.template.md`
+- `checklists/change-spec-readiness-checklist.md`
+- `AGENTS.md`
+
+## Expected Output
+
+- Ordered task list
+- Per task: objective, scope, out-of-scope, risk note
+- Validation criteria per task
+- Expected evidence per task
+- Recommended first task for implementation

package/opencode.jsonc

@@ -11,6 +11,11 @@
       "description": "Plan requirements, specs, technical plans, and PR breakdowns",
       "prompt": "{file:./opencode/agents/planner.md}"
     },
+    "spec-engineer": {
+      "mode": "primary",
+      "description": "Turn vague requests into lightweight spec-driven change artifacts",
+      "prompt": "{file:./opencode/agents/spec-engineer.md}"
+    },
     "implementer": {
       "mode": "primary",
       "description": "Implement features, fixes, and code changes",
@@ -204,6 +209,21 @@
       "description": "Prepare deployment readiness and rollback plan",
       "agent": "deploy-engineer",
       "template": "{file:./opencode/commands/deploy.md}"
+    },
+    "spec-create": {
+      "description": "Create a lightweight spec/change artifact from a vague request",
+      "agent": "spec-engineer",
+      "template": "{file:./opencode/commands/specs/create-spec-from-request.md}"
+    },
+    "spec-review": {
+      "description": "Review or improve spec readiness for implementation handoff",
+      "agent": "spec-engineer",
+      "template": "{file:./opencode/commands/specs/review-spec.md}"
+    },
+    "spec-tasks": {
+      "description": "Convert approved spec into small implementation tasks",
+      "agent": "spec-engineer",
+      "template": "{file:./opencode/commands/specs/spec-to-tasks.md}"
     }
   }
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.18.9",
+  "version": "1.18.10",
   "name": "@williambeto/ai-workflow",
   "description": "AI Workflow Kit repository for designing and validating AI-assisted software delivery workflows with Codex and OpenCode",
   "license": "MIT",

package/packages/ai-workflow/README.md

@@ -2,7 +2,7 @@
 
 `@williambeto/ai-workflow` is the npm CLI for installing AI Workflow Kit assets into a project.
 
-It prepares a repository for Codex and OpenCode workflows with local prompts, workflow scripts, managed `opencode.jsonc` sections, and doctor checks.
+It prepares a repository for Codex and OpenCode workflows with local prompts, generated workflow assets, managed `opencode.jsonc` sections, and doctor checks.
 
 ## Commands
 

package/runbooks/publication-readiness-checklist.md

@@ -0,0 +1,29 @@
+# Publication Readiness Checklist
+
+## Purpose
+
+Use this checklist before making the GitHub repository public or before a major public-facing release.
+
+## Checklist
+
+- [ ] `README.md` describes the project as public-ready enough for its current maturity.
+- [ ] `README.md` does not contain private-preview or not-ready-for-public language.
+- [ ] `SECURITY.md` exists and explains how to report vulnerabilities.
+- [ ] `package.json` metadata points to the public repository, license, and npm package.
+- [ ] Public docs do not contain local absolute paths.
+- [ ] Public docs do not contain private client, customer, or target-project names.
+- [ ] Historical repository names are removed, redacted, or clearly marked as historical.
+- [ ] GitHub-only folders (`evidence/`, `examples/`, `variants/`, `scripts/`, `tests/`) are appropriate for public readers.
+- [ ] CI and publish workflows reference secrets through GitHub Actions secrets only.
+- [ ] `npm run validate` passes.
+
+## Suggested verification commands
+
+```bash
+npm run validate
+grep -R --exclude=publication-readiness-checklist.md "/home/" README.md docs runbooks evidence packages examples variants || true
+grep -R --exclude=publication-readiness-checklist.md "private preview\|private-preview\|not ready for broad public" README.md docs runbooks packages evidence || true
+grep -R --exclude=publication-readiness-checklist.md "arco-ptp" README.md docs runbooks packages evidence || true
+```
+
+Review any matches before publication. Some historical references may be acceptable only when they are explicitly anonymized or explained.

package/runbooks/spec-driven-development.md

@@ -8,10 +8,9 @@ Standard flow:
 
 ```txt
 Request
-→ Spec draft
+→ Change proposal / lightweight spec
 → Spec review
-→ Technical plan
-→ PR breakdown
+→ Task breakdown
 → Implementation
 → Validation
 → Evidence report
@@ -32,6 +31,11 @@ For tiny docs-only edits, use proportional workflow.
 
 ## Assets to use
 
+- Lightweight change template: `templates/change-proposal.template.md`
+- Lightweight readiness checklist: `checklists/change-spec-readiness-checklist.md`
+- Request-to-spec command: `opencode/commands/specs/create-spec-from-request.md`
+- Spec-to-tasks command: `opencode/commands/specs/spec-to-tasks.md`
+- Spec-first owner: `opencode/agents/spec-engineer.md`
 - Spec template: `templates/SPEC.template.md`
 - Readiness checklist: `checklists/spec-readiness-checklist.md`
 - Draft prompt: `.codex/prompts/specs/create-spec-from-requirement.md`
@@ -39,15 +43,52 @@ For tiny docs-only edits, use proportional workflow.
 - Plan prompt: `.codex/prompts/specs/spec-to-technical-plan.md`
 - PR prompt: `.codex/prompts/specs/spec-to-pr-breakdown.md`
 
+## Artifact location convention (consumer project)
+
+Store generated spec artifacts in the consumer repository using this default path:
+
+```txt
+docs/specs/[spec-type]/[yyyy-mm-dd]-[change-slug]/
+```
+
+Allowed `<spec-type>` values:
+
+- `feature`
+- `bugfix`
+- `refactor`
+- `ui-change`
+- `architecture`
+- `workflow`
+- `integration`
+- `test-strategy`
+
+Recommended files inside each folder:
+
+```txt
+00-proposal.md
+01-spec.md
+02-design.md
+03-tasks.md
+04-validation.md
+05-handoff.md
+```
+
+For `tiny` specs, allow a minimal set:
+
+```txt
+00-proposal.md
+03-tasks.md
+04-validation.md
+```
+
 ## Connection to PR execution
 
 After spec review passes:
 
-1. produce technical plan;
-2. split into small PRs;
-3. implement PR 1 only;
-4. run validation before claiming success;
-5. return evidence for commands, changed files, and acceptance-criteria coverage.
+1. split into small implementation tasks (or PRs when needed);
+2. implement one scoped task/PR only;
+3. run validation before claiming success;
+4. return evidence for commands, changed files, and acceptance-criteria coverage.
 
 ## Required evidence after validation
 

package/templates/change-proposal.template.md

@@ -0,0 +1,97 @@
+# Change Proposal (Lightweight Spec)
+
+Suggested save path (consumer project):
+
+`docs/specs/<spec-type>/<yyyy-mm-dd>-<change-slug>/00-proposal.md`
+
+## Spec level
+
+`tiny` | `standard` | `deep`
+
+## Spec status
+
+`Draft` | `In review` | `Ready for implementation handoff` | `Needs clarification` | `Too broad` | `Blocked`
+
+## Title
+
+[Short change title]
+
+## Objective
+
+[Outcome this change must achieve]
+
+## Background
+
+[Context needed to understand this request]
+
+## Problem
+
+[Current pain, failure mode, or gap]
+
+## Proposed change
+
+[What will change and why this is the smallest safe approach]
+
+## Scope
+
+### Included
+
+- [In-scope item]
+
+### Out of scope
+
+- [Explicitly excluded item]
+
+## Requirements
+
+- [Clear, testable requirement]
+
+## Scenarios
+
+### Scenario 1 — [Name]
+
+- Given [state]
+- When [action]
+- Then [expected result]
+
+### Scenario 2 — [Name or `Not applicable`]
+
+- Given [state]
+- When [action]
+- Then [expected result]
+
+## Technical design
+
+- [High-level design choice]
+- [Constraints, integration points, and trade-offs]
+
+## Task breakdown
+
+1. [Small implementation task]
+2. [Small implementation task]
+3. [Small validation or hardening task]
+
+## Validation plan
+
+- [Command or check]
+- [Acceptance criteria coverage method]
+
+## Risks
+
+- [Risk + mitigation]
+
+## Open questions
+
+- [Question that blocks or may affect scope]
+
+## Expected evidence
+
+- Commands executed and results
+- Files changed
+- Acceptance criteria/scenario coverage
+- Untested areas and residual risks
+
+## Handoff
+
+- Recommended next owner: `implementer` | `planner`
+- Readiness: `Ready for implementation handoff` | `Needs clarification` | `Too broad` | `Blocked`