@chenmk/superflow 0.2.5 → 0.4.0

package/assets/skills-en/superflow-pipeline/SKILL.md

@@ -19,6 +19,38 @@ other:
 - Handoff files and state files are the memory boundary. Do not rely on chat
   memory after compaction.
 
+## Managed Work And Dual-Agent Closure
+
+When the user says to use Superflow for managed delivery and provides an
+implementation prompt, change directory, or direct task, use built-in managed
+mode. Do not require the user to name `superflow-pipeline`, roles, or CLI flags:
+
+```bash
+superflow pipeline "<implementation prompt, change directory, or direct task>" --managed --project "<project root>" \
+  --supervisor codex --executor claude --language en
+```
+
+Swap the roles when Claude is the current entry agent. The command always uses
+the independent background service while following the local task journal to a
+terminal state, then the current agent reads the report and summarizes in the
+same conversation. Losing the follower does not stop the task. Read
+`references/managed-work.md` before dispatch. Do not spawn the peer CLI by hand.
+
+Hard gates:
+
+- Persist one supervisor session and one executor session per task; resume exact IDs.
+- Task contract, event journal, review results, and evidence are authoritative.
+- Maximum 5 reviews, 7 executor calls, and 12 total agent calls.
+- Revalidate the frozen contract and hard limits on every start or resume. Engineering work cannot enter review with only one verification category.
+- Resolve a change directory through `.sdd/state.yaml` `implementation_prompt`, reject `tasks.md` as an execution entry, and freeze one prompt snapshot plus SHA-256 for both agents.
+- Supervisor is read-only; executor cannot edit `.superflow/tasks` or commit/push/publish.
+- A passing run stops at `awaiting_git_approval`; Git requires the user's approval.
+- Use `superflow status <project-root>` instead of model polling.
+- `superflow-managed-work-check.mjs` must pass before delivery-ready status.
+- Record the single delivery-ready event only after the integrity script passes.
+- After the managed command returns a terminal state, read the task report and summarize it to the user instead of returning only a task ID.
+- Freeze the selected language into the task contract. Executor and reviewer prompts, resumed rounds, journals, reports, notifications, and errors must inherit that language without switching mid-run.
+
 ## Phase Order
 
 Always route work through this order unless the task is explicitly a tweak or
@@ -37,6 +69,11 @@ hotfix:
 
 ## Routing
 
+- When the user explicitly asks for rigorous questioning, or a bounded feature
+  has unresolved owner decisions, mutually exclusive approaches, an unclear
+  source of truth, unclear acceptance behavior, or cross-system responsibility,
+  use `superflow-clarify` in embedded deep-clarification mode. This is a mode
+  inside the normal clarify phase, not a separate command the user must remember.
 - New or unclear requirement: use superflow-clarify.
 - Confirmed requirement needing full docs: use openspec-propose, then
   superflow-docs.
@@ -49,8 +86,47 @@ hotfix:
 - Urgent small behavior repair: use superflow-hotfix, unless API, DB, cross-repo,
   status, SQL, SDK, or real-entry gates are involved.
 
+## Embedded Deep Clarification
+
+When the router selects embedded deep clarification, follow these rules inside
+`superflow-clarify`:
+
+- Do not activate it for a clear, bounded hotfix or tweak whose intended behavior
+  and acceptance result are already evidenced. Do not turn routine work into an
+  interview.
+- Establish facts from the requirement, repository, configuration, tests, logs,
+  or available tools before asking the user. Ask only for a decision the user or
+  owner must make.
+- Ask exactly one decision question at a time. State the recommended option and
+  its important consequence, then wait for the answer before the next question.
+- After each answer, update `.sdd/handoff/brainstorm-summary.md` with
+  `confirmed`, `candidate`, `pending`, and `rejected` entries. Do not rely on
+  chat memory for a resolved decision.
+- Do not create or change proposal, spec, design, tasks, tests, or implementation
+  artifacts until all decisions that affect the current feature are confirmed or
+  explicitly marked blocked.
+- Exit deep clarification once only repository-verifiable facts remain and the
+  user confirms the current feature understanding. Continue through the existing
+  clarify workflow without invoking an external skill dependency.
+
 ## Required Artifacts
 
+### Canonical OpenSpec Change Directory (Blocking)
+
+- Superflow must use the OpenSpec CLI single-level layout:
+  `openspec/changes/<change-name>/`.
+- The release version belongs in the change name, not an intermediate
+  directory. Encode `v1.1.1` as `v1-1-1-<feature-slug>` and never create
+  `changes/v1.1.1/<feature-slug>/`.
+- Keep exactly one physical directory for each change. Do not create a
+  compatibility symlink, copied directory, or second canonical document tree.
+- Run `openspec new change <change-name>` first, then reuse that same physical
+  directory for status, instructions, strict validation, state, handoff, and
+  every Superflow guard.
+- If a nested version directory or symlinked change is found, stop document
+  generation, migrate it to one flat physical directory, and rerun
+  `openspec validate <change-name> --strict`.
+
 For a full change, the docs phase must create or refresh:
 
 - proposal.md

package/assets/skills-en/superflow-pipeline/references/api-design-template.md

@@ -11,6 +11,14 @@ Use api.md as the canonical contract before implementation.
 - Frontend mapping: screen field, API field, DTO/VO field, DB field, test case.
 - External dependency contract: SDK version, topic/path, parameter source,
   sample request/response, timeout and retry behavior.
+- External Integration Configuration And Deployment Contract for third-party
+  platforms/tools, SDKs, MQ/Kafka, callbacks, payment providers, cloud
+  services, or other external integrations. Inventory endpoint,
+  app/tenant/project IDs, Topic/Tag/Consumer Group, namespace, webhook,
+  ACL/role, feature switches, timeout, and credential references for local,
+  test, and production; record injection/provisioning method, runtime owner,
+  provisioning owner/time, readiness evidence, rollback, secret handling, and
+  blockers.
 - File contract when upload/download/export is involved: Content-Type,
   Content-Disposition, filename rule, body format, frontend detection rule.
 - Compatibility and migration notes.
@@ -20,3 +28,8 @@ Use api.md as the canonical contract before implementation.
 
 Do not allow design, tasks, tests, or prompts to proceed if API changes are only
 summarized as core fields, same as existing endpoint, or to be added later.
+Environment-dependent external configuration and server-side resources must
+not exist only as hard-coded annotations, constants, or business code. Test
+auto-creation, existing historical resources, or successful local startup do
+not prove production readiness; missing production provisioning evidence
+blocks release.

package/assets/skills-en/superflow-pipeline/references/batch-prompt-template.md

@@ -24,6 +24,22 @@ review-checklist.md, sdd-quality-gate.md, test-report.md, and technical design.
 - Do not change forbidden files or root aggregate docs from a worker batch.
 - Use TDD: record RED failure before GREEN success.
 - Do not mark mock-only or unit-only evidence as real integration.
+- For third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment
+  providers, cloud services, or other external integrations, inherit
+  `External Integration Configuration And Deployment Contract`. Cover
+  local/test/production sources and provisioning, injection/creation,
+  runtime/provisioning owners and timing, readiness evidence, rollback, secret
+  handling, and blockers. Do not hard-code environment-dependent values or
+  infer production readiness from test auto-creation.
+- For concurrent requests, batch issue/activation/renewal, duplicate callbacks
+  or consumption, and repeated external delivery, inherit `Concurrency And
+  Idempotency Ownership`. Define a stable business idempotency key,
+  application-layer atomic claim owner, short transaction boundary,
+  PENDING/SUCCESS/FAILED state machine, retry reuse of the original business
+  code, external-call boundary, and uncertain-result reconciliation. Release
+  database locks before external calls. A unique index is not the default and
+  may only be an optional fallback with explicit natural uniqueness,
+  historical cleanup, NULL/soft-delete behavior, and conflict handling.
 - For monetary changes, inherit `Money Precision Boundary`, retain
   calculation-state precision until the confirmed settlement/display boundary,
   record scale and rounding mode, forbid early rounding before slicing or

package/assets/skills-en/superflow-pipeline/references/document-templates.md

@@ -22,6 +22,11 @@
 - Source-of-truth contracts
 - Architecture boundary
 - Data model
+- Minimal Design Review: reuse evidence, necessity, simplest implementation,
+  removed/rejected complexity, and blockers
+- Count every new table, field, API, service, cache, async flow, scheduled job,
+  and compatibility layer; remove items without evidence
+- New-item counts: tables 0; fields 0; APIs 0; services/components 0; caches 0; MQ/events 0; scheduled jobs 0; compatibility layers 0. Replace each count.
 - Field semantics
 - Write/read loop
 - No-fallback decisions

package/assets/skills-en/superflow-pipeline/references/implementation-prompt-template.md

@@ -23,6 +23,23 @@ Superpowers technical design is canonical for source-level HOW and execution.
 - Field semantic contract checked.
 - Write-loop checked.
 - No-fallback boundary confirmed.
+- External Integration Configuration And Deployment Contract copied from the
+  API, quality gate, and technical design for third-party platforms/tools,
+  SDKs, MQ/Kafka, callbacks, payment providers, cloud services, or other
+  external integrations. Cover local/test/production sources and provisioning,
+  injection/creation, runtime/provisioning owners and timing, readiness
+  evidence, rollback, secret handling, and blockers. Do not hard-code
+  environment-dependent external values or treat test auto-creation as
+  production readiness evidence.
+- Concurrency And Idempotency Ownership copied from the technical design for
+  concurrent requests, batch issue/activation/renewal, duplicate callbacks or
+  consumption, and repeated external delivery. Define a stable business
+  idempotency key, application-layer atomic claim owner, short transaction
+  boundary, PENDING/SUCCESS/FAILED state machine, retry reuse of the original
+  business code, external-call boundary, and uncertain-result reconciliation.
+  Release database locks before external calls. A unique index is not the
+  default; it is only an optional fallback with explicit natural uniqueness,
+  historical cleanup, NULL/soft-delete behavior, and conflict handling.
 - Money Precision Boundary copied from the technical design when monetary
   behavior changes. Keep calculation-state precision until the confirmed
   settlement/display boundary, record scale and rounding mode, forbid early

package/assets/skills-en/superflow-pipeline/references/managed-work.md

@@ -0,0 +1,34 @@
+# Managed Work Rules
+
+Managed work is built into `superflow-pipeline`. The user only says to use
+Superflow and provides an implementation prompt, change directory, or direct
+task. Direct tasks receive a minimal contract. SDD work freezes the generated
+implementation prompt and never substitutes `tasks.md` for the execution prompt.
+
+Always dispatch through:
+
+```bash
+superflow pipeline "<implementation-prompt|change-dir|task>" --managed --project "<root>" \
+  --supervisor <codex|claude> --executor <claude|codex> --language <en|zh>
+```
+
+The command always starts the independent background service and follows the
+local event journal to a terminal state. Losing the follower does not stop the
+task. After return, the current agent reads the report and summarizes it in the
+original conversation.
+
+Hard gates:
+
+- Claim the 5/7/12 budgets before an Agent call.
+- Freeze the selected language into the contract; prompts, journals, reports, notifications, errors, and resumed rounds must use that same language.
+- Revalidate the frozen contract hash, non-overridable permissions, and 5/7/12 hard limits on every start and resume. Fail closed if persisted contract data changed.
+- Resolve change directories through `.sdd/state.yaml` `implementation_prompt`; treat `tasks.md` as a checklist only. Copy the prompt into a managed snapshot and freeze its SHA-256 for both agents.
+- Persist and resume exact supervisor and executor session IDs.
+- Treat `progress.jsonl`, the task contract, review results, and evidence as truth.
+- Executor cannot edit managed state or commit, push, publish, deploy, or bypass sandbox.
+- Supervisor cannot modify target files.
+- Non-zero exits, invalid JSON, missing session IDs, and review-time workspace drift block pass.
+- Engineering and SDD tasks need successful command evidence from at least two categories among build, test, and runtime/real invocation. Compile-only or unit-test-only delivery cannot enter formal review.
+- Run `superflow-managed-work-check.mjs <root> <task-id>` before delivery-ready.
+- Append the single `run.delivery_ready` event only after the integrity script passes. On failure, require human attention without leaving false delivery-ready evidence.
+- A passing run waits for explicit Git approval.

package/assets/skills-en/superflow-pipeline/references/quality-gate.md

@@ -9,13 +9,38 @@
 - Handoff files exist and hash is current.
 - design.md records OpenSpec/SDD as WHAT and Superpowers as HOW.
 - sdd-quality-gate.md records guard command and result.
+- design.md and sdd-quality-gate.md include a Minimal Design Review with reuse
+  evidence, necessity, simplest implementation, removed/rejected complexity,
+  counts of new tables/fields/APIs/services/caches/async flows/jobs/compatibility
+  layers, and a PASS/BLOCKED verdict. Only PASS may leave docs/design.
 
 ## Design Gate
 
 - Technical design exists for full workflow.
+- Technical design repeats the Minimal Design Review at source level. It extends
+  existing modules first and rejects speculative abstractions, parallel APIs or
+  models, derivable persistence, premature caches, and async compensation when
+  a direct synchronous design satisfies the contract.
 - Field/status reverse impact matrix exists when risky fields or states change.
 - Architecture boundary and call-direction matrix exists for cross-service or
   external flows.
+- External Integration Configuration And Deployment Contract exists for
+  third-party platforms/tools, SDKs, MQ/Kafka, callbacks, payment providers,
+  cloud services, or other external integrations. It inventories environment
+  sources and provisioning for endpoints, app/tenant/project IDs,
+  Topic/Tag/Consumer Group, namespace, webhook, ACL/role, switches, timeouts,
+  and credential references; names runtime/provisioning owners, timing,
+  readiness evidence, rollback, secret handling, and blockers; and forbids
+  environment-dependent hard-coded values. Test auto-creation, existing test
+  resources, or local startup do not prove production readiness.
+- Concurrency And Idempotency Ownership exists for concurrent requests, batch
+  issue/activation/renewal, duplicate callbacks/consumption, or repeated
+  external delivery. It defines the business idempotency key,
+  application-layer atomic claim owner, short transaction boundary,
+  PENDING/SUCCESS/FAILED state machine, retry code reuse, external-call
+  boundary, and uncertain-result reconciliation. A unique index is not the
+  default; it is only an optional fallback with explicit natural uniqueness,
+  historical cleanup, NULL/soft-delete behavior, and conflict handling.
 - Money precision boundary exists when amount, fee, discount, deduction,
   refund, sharing, payment, invoice, balance, electricity fee, service fee,
   package settlement, proration, allocation, reconciliation, or financial

package/assets/skills-en/superflow-pipeline/references/superpower-technical-design-template.md

@@ -35,6 +35,17 @@ canonical_sources:
 |---|---|---|---|---|---|
 | <R1/S1> | `<file>:<line>` | <observed fact> | <implementation approach> | <files> | <risk> |
 
+## Minimal Design Review
+
+| Design item | Existing capability/reuse evidence | Necessary? | Simplest implementation | Removed/rejected complexity | Evidence/blocker |
+| ----------- | ---------------------------------- | ---------- | ----------------------- | --------------------------- | ---------------- |
+| `<table/API/service/component/sync>` | `<existing source/API/table/dependency>` | `keep/remove/blocked` | `<minimum implementation>` | `<no parallel abstraction/cache/async/compat layer>` | `<anchor or blocker>` |
+
+New-item counts: tables 0; fields 0; APIs 0; services/components 0; caches 0; MQ/events 0; scheduled jobs 0; compatibility layers 0. Replace each count with the actual design total. Extend existing modules first. Do not persist values
+that can be derived safely, and do not add async compensation or caching when a
+single synchronous transaction closes the contract. Every retained item must
+explain why a simpler option fails; remove it when there is no evidence.
+
 ## Architecture Boundary And Call Direction
 
 Use this whenever the change crosses repositories, services, SDKs, MQ,
@@ -59,6 +70,52 @@ orchestrator unless the OpenSpec/SDD contract explicitly says that module owns
 the new entry point and records the owner approval. If the correct owner is
 unclear, mark the design blocked.
 
+## External Integration Configuration And Deployment Contract
+
+Use this whenever the change integrates with a third-party platform/tool, SDK,
+MQ/Kafka, callback, payment gateway, cloud service, or other external system.
+
+| External dependency/resource | Config/resource item | Local source/provisioning | Test source/provisioning | Production source/provisioning | Injection/creation method | Runtime owner | Provisioning owner/time | Readiness evidence | Rollback | Secret handling | Blocker |
+| ---------------------------- | -------------------- | ------------------------- | ------------------------ | ------------------------------ | ------------------------- | ------------- | ----------------------- | ------------------ | -------- | --------------- | ------- |
+| `<TDMQ>` | `<Consumer Group>` | `<auto/manual/IaC>` | `<existing resource>` | `<pre-created by ops>` | `<config/secret/IaC/console>` | `<service>` | `<owner + before deploy>` | `<console/API/trace>` | `<disable/rollback>` | `<secret reference only>` | `<none/blocker>` |
+
+Required checks:
+
+```bash
+rg -ni "https?://|endpoint|base.?url|app.?id|tenant|project.?id|topic|tag|consumer.?group|namespace|webhook|acl|role|secret|token|password|timeout" <source-and-config-paths>
+rg -ni "@.*Listener|new.*Client|builder\(|System\.getenv|ConfigurationProperties|Value\(" <source-and-config-paths>
+```
+
+Do not hard-code environment-dependent endpoints, resource names, identifiers,
+credentials, ACLs, or operational switches in annotations, constants, or
+business code. Stable protocol constants may remain code constants only when
+the design proves they are not environment-specific and no server-side
+resource must be provisioned. Test auto-creation, a successful local startup,
+or an already-existing test resource is not evidence that production is
+ready. Every server-side resource must have an explicit production owner,
+creation timing, readiness check, and rollback path. Missing production
+provisioning evidence is a blocker.
+
+## Concurrency And Idempotency Ownership
+
+Complete this section for concurrent requests, batch issue/activation/renewal,
+duplicate callbacks, duplicate consumption, or repeated external delivery.
+
+| Scenario | Business idempotency key | Claim owner/resource | Application-layer atomic claim | Short transaction boundary | State machine | Retry code reuse | External-call boundary | Uncertain-result handling | Unique-index role | Test evidence |
+| -------- | ------------------------ | -------------------- | ------------------------------ | -------------------------- | ------------- | ---------------- | ---------------------- | ------------------------- | ----------------- | ------------- |
+| `<batch issue>` | `<package+vehicle+period>` | `<period row>` | `<lock owner then persist PENDING>` | `<commit claim independently>` | `PENDING/SUCCESS/FAILED` | `<reuse original business code>` | `<call after commit>` | `<block duplicates and reconcile>` | `<not default; optional fallback>` | `<concurrent/duplicate/retry cases>` |
+
+Application-layer atomic claim is the default: use a stable business
+idempotency key, lock an explicit owner resource in a short transaction,
+persist `PENDING`, commit, and release the database lock before the external
+call. Update the state after the call; every retry reuses the original business
+code. An uncertain result blocks duplicate delivery and remains reconcilable.
+Do not use check-then-insert, process-local locks, or random IDs as cross-instance
+idempotency, and do not hold a database lock across an external call. A unique
+index is not the default; it is only an optional database fallback when natural
+uniqueness, historical cleanup, NULL/soft-delete behavior, and conflict handling
+are explicitly contracted.
+
 ## Field And Status Reverse Impact
 
 Use this whenever changing field values, enum/status values, derived fields,

package/assets/skills-en/superflow-pipeline/references/test-execution-template.md

@@ -38,3 +38,15 @@ rounded. Record currency, provider minor unit, pre/post-round values, residual
 recipient, and positive/zero/negative or refund, tied remainder, and idempotent
 recalculation evidence. FX cases also record base/quote, rate source, and target
 settlement rounding. A two-decimal display assertion alone is insufficient.
+
+## Closeout
+
+Verification Result: PASS / FAIL / BLOCKED / PARTIALLY_VERIFIED
+Archive Readiness: PASS / BLOCKED
+
+Required for `verify_mode: full`:
+
+- Test environment:
+- Branch/commit/build number or image:
+- Base URL:
+- Verification timestamp:

package/assets/skills-en/superflow-pipeline/scripts/superflow-archive.sh

@@ -131,7 +131,7 @@ GUARD="$SCRIPT_DIR/superflow-guard.sh"
 VALIDATE="$SCRIPT_DIR/superflow-yaml-validate.sh"
 CHANGE_DIR="$(cd "$CHANGE_DIR" && pwd)"
 CHANGE_NAME="$(basename "$CHANGE_DIR")"
-PROJECT_ROOT="$(cd "$CHANGE_DIR/../.." && pwd)"
+PROJECT_ROOT="$(cd "$CHANGE_DIR/../../.." && pwd)"
 ARCHIVE_ROOT="$PROJECT_ROOT/openspec/changes/archive"
 ARCHIVE_NAME="$CHANGE_NAME"