@double-codeing/flow2spec 3.0.8 → 3.0.9

package/docs/usage-guide.en.md

@@ -0,0 +1,165 @@
+[中文](./Flow2Spec使用说明.md) | [English](./usage-guide.en.md)
+
+# Flow2Spec Usage Guide
+
+## 1. What `init` Does
+
+Execute in the project root:
+
+```bash
+flow2spec init [cursor|claude|codex ...]
+# To force reset .Knowledge from template:
+flow2spec init [cursor|claude|codex ...] --reset-knowledge
+```
+
+| What `init` does | What `init` does NOT do |
+|---------|----------|
+| Fills in missing directories and template files | Write or update business document content |
+| Writes agent config root `rules/` `skills/` | Update `includeAny` business terms |
+| Aligns `manifest-routing` + `matchers/` package-level structure | Replace `f2s-*` skills for writing business semantics |
+| Overwrites `.Knowledge` template files with `--reset-knowledge` | Override existing `.Knowledge` content (without this flag) |
+
+> **`init` and "knowledge base upgrade" are two different things**: `init` only handles structural alignment — business semantics (topics content, routing terms, stock-docs/req-docs) are maintained by skills like `f2s-doc-add`, `f2s-kb-fix`, `f2s-kb-feat`, `f2s-kb-sync`, `f2s-ctx-build`, etc. For cross-version upgrades, use `f2s-kb-upgrade`. **Do not treat a standalone `init` as an upgrade command.**
+
+### `f2s-*` and `flow2spec.config.json`: Multi-Client, Multi-Layered Reminders (Authority Remains the Disk JSON)
+
+Before executing any **`f2s-*` skill**, the Agent needs to obtain the actual values of **`subAgent` / `switchAgentVerification` / `changeTracking`**, etc. Flow2Spec enforces this via **different mechanisms** on **different clients**; they **complement** each other and do **not** replace one another. **Authority always** resides in the project root **`flow2spec.config.json`** (call **Read** to verify against disk before proceeding into skill body).
+
+| Client | `init` Output & Behavior | Description |
+| --- | --- | --- |
+| **Cursor** | `.cursor/rules/f2s-config-check.mdc` (`alwaysApply`) | Rule requires: **Read(`flow2spec.config.json`)** before entering skill body. |
+| **Claude Code** | `.claude/hooks/f2s-config-inject.js` + `.claude/settings.json` (PreToolUse, `Skill` matching) | Injects a config summary when invoking **`f2s-*` Skill**; when **file is missing, JSON is invalid, or hook throws an unexpected exception**, it also injects a **notice + default semantics consistent with "file not found"** to avoid silent failure; it is still recommended to **Read** for confirmation when in doubt or after config changes. |
+| **Codex** | `.codex/AGENTS.md` top-level mandatory step + `{{FLOW2SPEC_PROJECT_CONFIG}}` expansion table | **Read** is a hard requirement; the config table is a **snapshot from the last `flow2spec init`** — when it differs from disk, **Read** takes precedence. The adjacent **`.codex/topics/f2s-config-check.md`** shares its origin with the Cursor rule (including the **changeTracking** detail table); open it **as needed** — it does not need to be grouped with the three "topic long-form" examples as required reading. |
+| **Knowledge Base (optional)** | When `.Knowledge/manifest-routing` hits **`config-precheck`** | `.Knowledge/topics/f2s-config-precheck.md` is a **routing summary** that links to the Codex long-form article; Flow2Spec does **not** maintain a second full copy in `.Knowledge`, nor does it replace a `Read` of the JSON. |
+
+For field semantics and default value rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.en.md). For the design perspective, see [Design Principles § 4.5.1](./design-principles.en.md).
+
+---
+
+## 2. Directory Conventions
+
+Core distinction: `stock-docs/` holds solidified documents (driving knowledge routing), `req-docs/` holds technical designs (driving coding implementation); they are not interchangeable.
+
+See [Directory Conventions](./directory-conventions.en.md) for the full directory description.
+
+---
+
+## 3. Typical Workflows
+
+### Requirements Planning and Implementation
+
+```
+f2s-req-plan
+```
+
+Provide a path to the technical design document or a requirements description. A draft task checklist is produced first and awaits confirmation. After confirmation, implementation proceeds according to the checklist. A `.task/` task checklist is always created — no `changeTracking` configuration is needed. Suitable for scenarios where you want to see the full picture before starting, or need cross-session progress tracking.
+
+### Change Tracking and Cross-Session Continuation
+
+```
+# Automatic mode: enabled by config (independent per skill)
+flow2spec.config.json → changeTracking.feat / fix / implement: true
+
+# Explicit mode: call f2s-req-plan (planning + implementation, no config dependency)
+f2s-req-plan
+```
+
+**Automatic mode**: When enabled, `f2s-kb-feat` / `f2s-kb-fix` / `f2s-implement-tech-design` automatically create a task checklist under `.task/active/`, check off steps progressively, and archive upon completion. In subsequent sessions, when describing related content, the `f2s-task` rule automatically matches and loads the remaining checklist — no need to re-explain the context.
+
+**Explicit mode**: Call `f2s-req-plan` directly — regardless of the `changeTracking` configuration, a task checklist is always created and code is implemented against it. Suitable for scenarios where you want to confirm the full picture before taking action.
+
+### New Feature Development
+
+```
+f2s-req-clarify → f2s-req-backend → implement-tech-design → f2s-kb-feat
+```
+
+When requirements are already clear, `f2s-req-clarify` can be skipped, starting directly from `f2s-req-backend`. After the technical design is written into `req-docs/`, the `implement-tech-design` rule drives coding.
+
+### Document Ingestion
+
+```
+New architecture document ingestion: f2s-doc-arch → f2s-doc-final → f2s-ctx-build
+PDF document ingestion:          f2s-doc-pdf  → f2s-doc-final → f2s-ctx-build
+```
+
+Integrate architecture descriptions or PDF technical designs into the knowledge routing (generates topics/matchers/manifest-routing).
+
+### PDF-Based Implementation
+
+```
+f2s-doc-pdf → implement-tech-design
+```
+
+Convert a PDF technical design to Markdown and place it in `req-docs/`, then let the `implement-tech-design` rule drive coding.
+
+### Backfilling Existing Capabilities
+
+```
+f2s-doc-add      # Aggregate multiple files, extract from source code / documents
+f2s-kb-sync      # Infer already-implemented capabilities from current session
+```
+
+Use these when code has already been shipped but the knowledge base has no record. `f2s-doc-add` is suitable for batch imports; `f2s-kb-sync` is suitable for real-time consolidation at the end of a session.
+
+### Routine Maintenance
+
+```
+f2s-kb-fix       # Fix implementation or rule errors, auto-sync knowledge base
+f2s-kb-feat      # Add new capabilities, auto-sync knowledge base
+f2s-kb-sync      # Periodic sync or backfill
+f2s-kb-merge     # Resolve context conflicts after Git merges
+```
+
+### Cross-Version Knowledge Base Upgrade
+
+```
+f2s-kb-migrate (Legacy V1: old knowledge base) → f2s-kb-upgrade
+f2s-kb-upgrade (Current V2+: already has .Knowledge; includes npm v3.x projects, etc.; see skill step 0)
+```
+
+---
+
+## 4. Agent Execution Configuration
+
+Controlled via the project root `flow2spec.config.json`. For complete field rules, see [Commands Reference § 6) Sub-Agent Configuration](./commands-reference.en.md). **How each client is reminded to read the config, and why `Read` remains authoritative** — see **§ 1** (this § only explains **when** to toggle each switch).
+
+**When to enable `subAgent: true`**: When the task is large (multi-module parallel implementation, batch document ingestion, large-scale migration). When enabled, each skill decides whether to actually split based on its own size threshold; tasks below the threshold are still completed within the main agent.
+
+**When to enable `switchAgentVerification: true`**: When higher write consistency is needed (large-scale migration, critical design implementation). The trade-off is increased execution rounds; for routine maintenance, the default `false` is sufficient. Requires `subAgent: true` to trigger the "main-writes, sub-verifies" cross-check direction.
+
+**When to enable `changeTracking.*`**: When you want each skill execution to automatically leave a resumable task checklist. Each skill sub-item is independently configurable without mutual interference:
+
+```json
+{
+  "changeTracking": {
+    "feat": true,
+    "fix": false,
+    "implement": true
+  }
+}
+```
+
+If you prefer not to rely on configuration and want to explicitly plan tasks on demand, use `f2s-req-plan` directly.
+
+---
+
+## 5. Customization Suggestions
+
+- When customizing the "implement from technical design" logic for your project, prioritize adjusting **`f2s-implement-tech-design`**: Cursor `.cursor/rules/f2s-implement-tech-design.mdc`, Claude `.claude/rules/f2s-implement-tech-design.md`; Codex uses `.codex/AGENTS.md` and associated `skills/` as the source of truth.
+- Running `init` again by default only fills in missing templates and performs package-level structural alignment — it does **not** replace `f2s-*` skills for maintaining business content. To reset `.Knowledge` from the template, add `--reset-knowledge`.
+
+---
+
+## 6. Skill Identification
+
+Skills are triggered by matching `name` and `description`. Files are located under `config-root/skills/*/SKILL.md`.
+
+---
+
+## 7. Related Documents
+
+- [Commands Reference](./commands-reference.en.md)
+- [Directory Conventions](./directory-conventions.en.md)
+- [Architecture](./architecture.en.md)
+- [Usage Scenarios](./usage-scenarios.en.md)

package/docs/usage-scenarios.en.md

@@ -0,0 +1,222 @@
+[中文](./Flow2Spec-使用案例-模拟对话.md) | [English](./usage-scenarios.en.md)
+
+# Flow2Spec Usage Scenarios (Simulated Dialogues)
+
+The following examples revolve around the same e-commerce project, covering the full pipeline from requirements clarification through post-launch maintenance.
+
+**Prerequisite**: The project has executed `flow2spec init`, and `flow2spec.config.json` uses the default configuration (`subAgent: false`). `f2s-*` skills do not modify the configuration root `rules/` or `skills/` files.
+
+---
+
+## Scenario 1: New Requirement -> Clarification -> Technical Design
+
+**You**
+
+> /f2s-req-clarify The product team provided a refund requirement doc, but it does not specify whether partial refunds and full refunds go through the same API, or whether points should be reversed after a successful refund. The document is at `.Knowledge/req-docs/refund-requirements-v1.md`.
+
+**Agent**
+
+> I have read the requirements document. There are a few points that need clarification:
+>
+> 1. Do partial refunds and full refunds reuse the same endpoint, differentiated by the `amount` field, or should they be two separate endpoints?
+> 2. Should points be reversed after a successful refund? If the reversal fails, should it block the refund flow?
+> 3. Is the refund processed synchronously or asynchronously (T+1)?
+> 4. Is there a seller-side review step?
+
+**You**
+
+> 1. Same endpoint, differentiated by amount; 2. Points are reversed; failure does not block the flow, retry asynchronously; 3. Asynchronous T+1; 4. No review needed.
+
+**Agent**
+
+> Clarification complete. Run `/f2s-req-backend` to produce the technical design.
+
+**You**
+
+> /f2s-req-backend
+
+**Agent**
+
+> Generated `.Knowledge/req-docs/refund-tech-design.md`, which includes:
+> - API design: `POST /refunds`, `amount` field distinguishes full / partial refunds
+> - State machine: `PENDING -> SUCCESS / FAILED`
+> - Points reversal: asynchronous queue, failures go to dead letter queue, alert for manual handling
+> - Error code list
+>
+> Next step: say "implement according to `.Knowledge/req-docs/refund-tech-design.md`" to trigger coding.
+
+---
+
+## Scenario 2: Architectural Documentation into Knowledge Base
+
+**You**
+
+> /f2s-doc-arch Help me draft an order service architecture document, focusing on the creation flow, payment callback, idempotency, and message delivery. The code is in `src/order` and `src/payment`.
+
+**Agent**
+
+> Scanned the relevant directories. Generated `.Knowledge/stock-docs/order-service-architecture-draft.md`, which includes:
+> - Module boundaries and dependencies
+> - Creation flow sequence diagram
+> - Payment callback idempotency mechanism (based on the `payment_callback_log` table)
+> - Message delivery retry strategy
+>
+> Confirm it looks good, then run `/f2s-doc-final` to normalize the format.
+
+**You**
+
+> /f2s-doc-final .Knowledge/stock-docs/order-service-architecture-draft.md
+
+**Agent**
+
+> Generated `.Knowledge/stock-docs/order-service-architecture-final.md`, formatted according to the final-draft template, with placeholders for items still to be filled in.
+
+**You**
+
+> f2s-ctx-build .Knowledge/stock-docs/order-service-architecture-final.md
+
+**Agent**
+
+> Knowledge base sync complete:
+> - Added `.Knowledge/topics/order-service.md`
+> - Updated `.Knowledge/manifest-routing.json` (added routing rule)
+> - Generated `.Knowledge/matchers/order-service.json` (keywords: order creation, payment callback, idempotency, message delivery)
+> - Updated `.Knowledge/index.md`
+>
+> Future tasks related to the order service will automatically hit this topic.
+
+---
+
+## Scenario 3: Implementation from Technical Design
+
+**You**
+
+> Implement according to `.Knowledge/req-docs/refund-tech-design.md`. Only modify `src/refund/`; do not touch the payment module.
+
+**Agent**
+
+> I have read the design document. Task list for implementation:
+>
+> 1. Create `RefundController` with `POST /refunds`
+> 2. Create `RefundService` with state machine transition logic
+> 3. Create `RefundRepository` for the `refund` table
+> 4. Create `PointRollbackProducer` to send rollback messages to the points queue
+> 5. Unit tests covering state machine transitions
+>
+> Before proceeding, I need to confirm:
+> - Does the `refund` table already exist, or do I need to generate a migration?
+> - What is the points queue topic name?
+
+**You**
+
+> The table already exists; no migration needed. The topic is `point-rollback-events`.
+
+**Agent**
+
+> Completed all 5 tasks above, all within `src/refund/`. Did not touch `src/payment/`.
+>
+> **Requires manual action**:
+> - Consumer side for `point-rollback-events` (on the points service side)
+> - Dead letter monitoring and alerting rule configuration
+>
+> Recommend running `/f2s-kb-feat` to sync this new capability into the knowledge base.
+
+---
+
+## Scenario 4: PDF Design -> Implementation
+
+**You**
+
+> /f2s-doc-pdf /Users/me/Downloads/marketing-coupon-v2.pdf
+
+**Agent**
+
+> Converted and saved as `.Knowledge/req-docs/marketing-coupon-v2.md`. Filled in the idempotency handling flow description and error code explanations that were missing in the PDF.
+
+**You**
+
+> Implement according to `.Knowledge/req-docs/marketing-coupon-v2.md`
+
+**Agent**
+
+> I have read the design document. Task list for implementation:
+>
+> 1. Create `CouponController` (coupon claim, redemption, and return endpoints)
+> 2. Create `CouponService` with inventory deduction and idempotency checks
+> 3. ...
+>
+> Before proceeding, I need to confirm: is the coupon inventory managed via Redis or database row locks?
+
+---
+
+## Scenario 5: Post-Implementation Knowledge Base Recording
+
+**You**
+
+> /f2s-kb-sync The refund feature has gone live. Help me record the payment failure retry queue naming, dead letter table fields, and monitoring alerting criteria into the knowledge base. Give me an outline first so I can confirm before you write.
+
+**Agent**
+
+> Knowledge base update outline (pending confirmation):
+>
+> **Update topic**: `order-service` (already exists)
+>
+> - Add "Payment Failure Retry Mechanism": queue name `payment-retry-queue`, max retries 3, intervals 30s / 120s / 300s
+> - Add "Dead Letter Table": table name `payment_dead_letter`, fields `order_id / error_code / retry_count / created_at`
+> - Add "Monitoring Criteria": alert threshold `retry_count >= 3`, notification channel DingTalk
+>
+> Confirm to write, or let me know what needs to be changed.
+
+**You**
+
+> Confirm, go ahead and write.
+
+**Agent**
+
+> Updated `.Knowledge/topics/order-service.md`. `manifest-routing` unchanged (topic already exists).
+
+---
+
+## Scenario 6: Non-compliant Implementation Found, Fix and Sync Knowledge Base
+
+**You**
+
+> /f2s-kb-fix `RefundService` directly calls `new RestTemplate()`, which violates the Spring Bean injection convention.
+
+**Agent**
+
+> Fixed: Line 34 of `RefundService.java` changed to constructor injection; `RefundConfig` supplemented with `@Bean` declaration.
+>
+> Knowledge base synced: the "HTTP Client Conventions" section in `.Knowledge/stock-docs/` has been updated, noting that `RestTemplate` must be injected as a Bean, and direct instantiation is prohibited.
+
+---
+
+## Scenario 7: Knowledge Base Conflicts After Git Merge
+
+**You**
+
+> /f2s-kb-merge `.Knowledge/index.md` and `.Knowledge/stock-docs/order-service-architecture-final.md` have conflict markers after the merge. I have already resolved the conflicts in the business code manually.
+
+**Agent**
+
+> Scanned the conflict markers in both files:
+>
+> - `index.md`: 2 conflicts, both in topic description fields. Took the HEAD version (newer content). Resolved automatically.
+> - `order-service-architecture-final.md`: 1 conflict. The "monitoring alert threshold" differs between branches (3 vs. 5). Please confirm which one to keep.
+
+**You**
+
+> Use 3.
+
+**Agent**
+
+> All conflict markers have been cleaned up per your confirmation. The files are ready to commit.
+
+---
+
+## Related Documentation
+
+- [Usage Guide](./usage-guide.en.md)
+- [Commands Reference](./commands-reference.en.md)
+- [Directory Conventions](./directory-conventions.en.md)
+- [Architecture](./architecture.en.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@double-codeing/flow2spec",
-  "version": "3.0.8",
+  "version": "3.0.9",
   "description": "在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则 f2s-karpathy-guidelines，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。",
   "homepage": "https://github.com/Lands-1203/Flow2Spec#readme",
   "repository": {

package/templates/skills/f2s-ctx-build/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: f2s-ctx-build
 description: 根据 .Knowledge/stock-docs 文档生成知识路由主题与索引；触发：生成项目上下文、f2s-ctx-build、终稿生成上下文
+---
 
 > 执行口径：本技能只维护 `.Knowledge`（`topics/index/manifest-routing/matchers` 分片），不改配置根 `rules/skills`。不再维护 `.Knowledge/manifest-matchers.json`（已废弃聚合文件；`flow2spec init` 会删除遗留副本）。