diff --git a/.agent-taskgraph/DECISIONS.md b/.agent-taskgraph/DECISIONS.md new file mode 100644 index 00000000..ac22132c --- /dev/null +++ b/.agent-taskgraph/DECISIONS.md @@ -0,0 +1,17 @@ +# Decisions + +## 2026-08-10 Product Direction + +- Original product: `Aetherbound Guild / 裂脉远征团`. +- Familiar, readable magical guild and job fantasy; no Dragon Quest or reference-game expression is copied. +- Complete scope: 30 named characters, 12 base jobs, 24 advanced jobs, 100 enemy identities, 8 chapters and 320 equipment/items. +- Target playtime: 25-35 hour first campaign, 60-80 hour build completion and roughly 100 hour full collection/high difficulty. +- Landscape 16:9; full 2D Japanese hand-drawn direction using layered rigs, equipment layers, authored key poses and unique portraits/illustrations. +- Formal implementation begins only after the complete design package, HTML gallery and interactive design prototype pass Owner review. + +## 2026-08-10 Execution Decision + +- Use Agent TaskGraph protocol 0.8.0-beta.10. +- Run three parallel non-overlapping design workers, then presentation, integration and an independent reviewer. +- All worker and reviewer sessions use Codex `gpt-5.6-sol`, `xhigh`, project-level `yolo`. +- Native `wait_agent` is the monitoring mechanism; no shell sleep or passive chat waiting. diff --git a/.agent-taskgraph/PROJECT.md b/.agent-taskgraph/PROJECT.md new file mode 100644 index 00000000..92d5aaaa --- /dev/null +++ b/.agent-taskgraph/PROJECT.md @@ -0,0 +1,85 @@ +# Project Profile: Aetherbound Guild + +## What It Is + +`Aetherbound Guild / 裂脉远征团` is an original landscape 2D Japanese hand-drawn magic-guild expedition strategy game. The current stage is complete pre-production design and a reviewable HTML prototype; formal engine development is frozen. + +## Technology And Structure + +There is no runtime engine yet. Markdown/JSON/CSV are design authority. HTML/CSS/JS are allowed only for design prototypes and the gallery. + +- `docs/reference/`: evidence-labeled reference research +- `docs/product/`: player, systems, economy, balance, save and failure contracts +- `docs/content/`: complete characters, professions, enemies, equipment and chapters +- `docs/presentation/`: screen map, UI, art, animation, asset and audio specifications +- `docs/prototype/`: HTML design gallery and interaction-prototype specifications +- `docs/reviews/`: independent reviews + +## Hard Rules + +- Authorized private reference material yields structural lessons only. Do not copy expression, names, prose, formulas, layouts, assets, audio or code. +- No game runtime code, engine project, bulk final assets, package, store action or release before the complete design package passes independent and Owner review. +- Parallel workers have exclusive non-overlapping directories. PMO alone owns `.agent-taskgraph/` and shared root files. +- Every content row needs mechanical purpose, interactions, progression placement, presentation, asset/audio needs and validation. No filler rows. +- Every research claim is labeled `direct observation`, `inference`, `assumption` or `unknown`. +- Use explicit staging paths. Never commit commercial reference assets, credentials, caches or generated packages. + +## Authorization And Execution + +| Setting | Confirmed Value | +|---|---| +| Agent TaskGraph protocol | 0.8.0-beta.10 | +| Source baseline | READY: repo `/Users/wusumac/Documents/game/aetherbound_guild`, HEAD `948d7fb`, branch `main`, initially clean | +| Complex spec | FROZEN by Owner for design-batch-01 on 2026-08-10 | +| Session creation | Authorized for this multi-agent design batch | +| Staffing preview | Three parallel non-overlapping design Goals authorized | +| Staffing changes | Owner confirmation required | +| Human Gates | dependency install, deletion, paid expansion, merge to a protected remote, engine implementation, packaging, publishing | +| Context mode | balanced; maximum 8 mandatory reads per Goal | + +## Execution Profile + +| Field | Value | +|---|---| +| Status | CONFIRMED | +| Confirmed by/at | Owner / 2026-08-10T16:42:21+08:00 / design-batch-01 | +| Runtime | codex-native `collaboration.spawn_agent` | +| Control | Host-native subagents; PMO monitors with `list_agents` and `wait_agent` | +| Machine | `wusumacdeMac-mini.local` | +| Flavor | codex | +| Model policy | fixed | +| Model/effort | `gpt-5.6-sol` / `xhigh` | +| Catalog evidence | model accepted by native spawn catalog; codex-cli 0.146.0; per-session evidence recorded after spawn | +| Permission | `yolo`; host project permission profile is unrestricted without interactive command prompts | +| Permission scope | runtime-only; Human Gates above remain intact | +| Visibility | PMO-managed native subagents; live status via collaboration tree | +| Fallback | none; a spawn mismatch pauses the Goal and is reported | + +## Shared File Locks + +PMO alone writes `.agent-taskgraph/`, root `README.md`, root `AGENTS.md` and shared indexes. Phase-one workers write only one of `docs/reference/`, `docs/product/`, or `docs/content/`. `docs/presentation/`, `docs/prototype/` and cross-domain indexes are assigned serially after phase one. + +## Roles And Acceptance + +| Role | Owned Scope | Primary Acceptance | +|---|---|---| +| reference-researcher | `docs/reference/` | evidence labels, provenance links, direct/inferred/unknown counts | +| systems-designer | `docs/product/` | complete systems contracts, formulas, state choices and failure boundaries | +| content-architect | `docs/content/` | exact row counts, references, differentiation and no-filler audit | +| presentation-designer | `docs/presentation/`, `docs/prototype/` | all screens/states, landscape HTML, art/audio asset coverage | +| design-integrator | cross-domain index only | link, count, coverage and consistency validation | +| independent-reviewer | `docs/reviews/` only | read-only package review against spec and graph | + +## Local Environment + +| Capability | State | Evidence | +|---|---|---| +| Git | READY | Git root and initial commit `948d7fb` on `main` | +| Codex | READY | `/Users/wusumac/.local/bin/codex`, codex-cli 0.146.0 | +| Native subagents | READY | `spawn_agent`, `list_agents`, `wait_agent`, `send_message` available | +| create_thread/wait_threads | Unavailable in current tool surface | Native subagents are the approved runtime for this batch | +| Monitoring | RUNNING | Native `wait_agent`, interval up to 600s; inspect collaboration tree plus Goal/ledger; no shell sleep | + +## Archive Convention + +`STATUS.md` lists active/review tasks only. Completed task directories move to `archive/YYYY-MM/` after reports and evidence are durable. diff --git a/.agent-taskgraph/ROLES.md b/.agent-taskgraph/ROLES.md new file mode 100644 index 00000000..eacf6cdd --- /dev/null +++ b/.agent-taskgraph/ROLES.md @@ -0,0 +1,18 @@ +# Role Registry + +> Team revision: `rev-1` + +| Role ID | Name | Lifecycle | State | Core Responsibility | Current Goal | Session ID | +|---|---|---|---|---|---|---| +| reference-researcher | Reference Researcher | persistent | assigned | Evidence-labeled private reference census and transferable structural lessons | task:ABG-REF-CENSUS | PENDING | +| systems-designer | Systems Designer | persistent | assigned | Original core loop, battle, professions, skills, economy, balance, save and failure contracts | task:ABG-SYSTEM-DESIGN | PENDING | +| content-architect | Content Architect | persistent | assigned | Original characters, professions, enemies, equipment, chapters and collection matrices | task:ABG-WORLD-CONTENT | PENDING | +| presentation-designer | Presentation Designer | persistent | available | Complete screen/state map, UI, art, animation, assets, audio and HTML prototype | none | PENDING | +| design-integrator | Design Integrator | task-scoped | available | Cross-domain indexes, consistency checks and gallery assembly | none | PENDING | +| independent-reviewer | Independent Reviewer | task-scoped | available | Read-only originality, completeness, coherence and feasibility review | none | PENDING | + +## Staffing History + +| Time | Team Revision | Change | Owner Authorization | Result | +|---|---|---|---|---| +| 2026-08-10 | rev-1 | Initial three-worker design team | Owner requested agent-taskgraph acceleration with Codex 5.6 sol, xhigh, yolo | Profiles created; sessions pending | diff --git a/.agent-taskgraph/STATUS.md b/.agent-taskgraph/STATUS.md new file mode 100644 index 00000000..63cd4d4b --- /dev/null +++ b/.agent-taskgraph/STATUS.md @@ -0,0 +1,8 @@ +# Active Task Board + +| Task ID | Title | State | Owner | Attempt | Last Update | Blocker | +|---|---|---|---|---|---|---| + +## Batch Summary + +Batch 01 has three inbox design Goals pending session identity ACK. After all pass, the graph continues serially through presentation, integration, independent review and Owner Gate. diff --git a/.agent-taskgraph/archive/.gitkeep b/.agent-taskgraph/archive/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.agent-taskgraph/graph.yaml b/.agent-taskgraph/graph.yaml new file mode 100644 index 00000000..dcf22c5f --- /dev/null +++ b/.agent-taskgraph/graph.yaml @@ -0,0 +1,101 @@ +version: 1 +batch: + id: "design-batch-01" + revision: "graph-r1" + spec: ".agent-taskgraph/spec.md" + spec_revision: "design-spec-r1" + approved_by: "Owner" + approved_at: "2026-08-10T16:42:21+08:00" + max_concurrency: 3 + +nodes: + - id: "ref_census" + title: "Evidence-labeled reference runtime content census" + kind: "expert" + goal_ref: "task:ABG-REF-CENSUS" + needs: [] + consumes: ["authorized private reference archive", "existing structural audits"] + produces: ["docs/reference/REFERENCE_RUNTIME_CENSUS.md", "docs/reference/TRANSFERABLE_STRUCTURE_LESSONS.md"] + writes: ["docs/reference/"] + acceptance: ["Every count is direct observation, inference or unknown", "No commercial reference asset is copied into Git"] + on_pass: "merge_design_package" + on_fail: "failed" + max_attempts: 2 + + - id: "system_design" + title: "Original systems, economy and balance contracts" + kind: "expert" + goal_ref: "task:ABG-SYSTEM-DESIGN" + needs: [] + consumes: [".agent-taskgraph/spec.md", "repository product boundary"] + produces: ["docs/product/GAME_PRODUCT_CONTRACT.md", "docs/product/SYSTEMS_AND_BATTLE.md", "docs/product/ECONOMY_AND_BALANCE.md", "docs/product/SAVE_AND_FAILURE_CONTRACT.md"] + writes: ["docs/product/"] + acceptance: ["Every loop produces state-dependent decisions", "Formulas and failure boundaries are explicit", "Five pacing profiles are specified"] + on_pass: "presentation_design" + on_fail: "failed" + max_attempts: 2 + + - id: "world_content" + title: "Complete original world and content matrices" + kind: "expert" + goal_ref: "task:ABG-WORLD-CONTENT" + needs: [] + consumes: [".agent-taskgraph/spec.md", "repository originality boundary"] + produces: ["docs/content/CHARACTER_BIBLE.md", "docs/content/PROFESSION_AND_SKILL_MATRIX.md", "docs/content/ENEMY_BESTIARY.md", "docs/content/EQUIPMENT_CATALOG.md", "docs/content/CAMPAIGN_AND_CHAPTERS.md", "docs/content/ACHIEVEMENTS_AND_COLLECTIONS.md"] + writes: ["docs/content/"] + acceptance: ["Exact 30/12/24/100/8/320 counts", "At least 120 behavior-changing items", "No filler rows or copied expression"] + on_pass: "presentation_design" + on_fail: "failed" + max_attempts: 2 + + - id: "presentation_design" + title: "Complete UI, art, animation, audio and landscape gallery design" + kind: "worker" + goal_ref: "task:ABG-PRESENTATION" + needs: ["system_design", "world_content"] + consumes: ["docs/product/", "docs/content/"] + produces: ["docs/presentation/", "docs/prototype/"] + writes: ["docs/presentation/", "docs/prototype/"] + acceptance: ["All player-facing screens and key states are shown", "Landscape 16:9 mobile/desktop layouts are readable", "Asset, animation, music and SFX inventories are complete"] + on_pass: "merge_design_package" + on_fail: "failed" + max_attempts: 2 + + - id: "merge_design_package" + title: "Integrate and validate the complete design package" + kind: "merge" + goal_ref: "task:ABG-DESIGN-INTEGRATION" + needs: ["ref_census", "presentation_design"] + consumes: ["docs/reference/", "docs/product/", "docs/content/", "docs/presentation/", "docs/prototype/"] + produces: ["docs/DESIGN_PACKAGE_INDEX.md", "docs/reviews/DESIGN_COVERAGE_AUDIT.md"] + writes: ["docs/DESIGN_PACKAGE_INDEX.md", "docs/reviews/DESIGN_COVERAGE_AUDIT.md"] + acceptance: ["Links and exact counts validate", "No cross-document contradictions", "All required package elements are indexed"] + on_pass: "independent_review" + on_fail: "failed" + max_attempts: 2 + + - id: "independent_review" + title: "Independent pre-development readiness review" + kind: "verifier" + goal_ref: "task:ABG-DESIGN-REVIEW" + needs: ["merge_design_package"] + consumes: ["complete design package at fixed Git revision"] + produces: ["docs/reviews/INDEPENDENT_DESIGN_REVIEW.md"] + writes: ["docs/reviews/INDEPENDENT_DESIGN_REVIEW.md"] + acceptance: ["Originality, completeness, coherence, comprehension, feasibility and balance gates pass"] + on_pass: "owner_design_gate" + on_fail: "failed" + max_attempts: 1 + + - id: "owner_design_gate" + title: "Owner reviews complete gallery and prototype" + kind: "human_gate" + goal_ref: "decision:ABG-OWNER-DESIGN-GATE" + needs: ["independent_review"] + consumes: ["published gallery", "interactive design prototype", "independent review"] + produces: ["owner accept, revise or reject decision"] + writes: [] + acceptance: ["Owner explicitly accepts design for vertical-slice development"] + on_pass: "done" + on_fail: "failed" + max_attempts: 1 diff --git a/.agent-taskgraph/queue/active/.gitkeep b/.agent-taskgraph/queue/active/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.agent-taskgraph/queue/done/.gitkeep b/.agent-taskgraph/queue/done/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.agent-taskgraph/queue/failed/.gitkeep b/.agent-taskgraph/queue/failed/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.agent-taskgraph/queue/inbox/.gitkeep b/.agent-taskgraph/queue/inbox/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.agent-taskgraph/queue/review/.gitkeep b/.agent-taskgraph/queue/review/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.agent-taskgraph/roles/content-architect/ROLE.md b/.agent-taskgraph/roles/content-architect/ROLE.md new file mode 100644 index 00000000..2c43f431 --- /dev/null +++ b/.agent-taskgraph/roles/content-architect/ROLE.md @@ -0,0 +1,17 @@ +# Role: Content Architect + +| Field | Value | +|---|---| +| Role ID | content-architect | +| Team revision | rev-1 | +| Origin | initial:design-spec-r1/graph-r1 | +| Lifecycle | persistent | +| State | assigned | +| Core responsibility | Original world, characters, professions, enemies, equipment, chapters and collection matrices | +| Owned scope | `docs/content/` | +| Explicitly not responsible | Reference census, system formulas authority, UI/art production, runtime development | +| Default runtime | codex / gpt-5.6-sol / xhigh / yolo | +| Current Goal | task:ABG-WORLD-CONTENT | +| Session ID | PENDING | + +Every row must affect play and include cross-references, presentation needs and validation. Exact counts are mandatory; filler and copied expression are rejected. diff --git a/.agent-taskgraph/roles/reference-researcher/ROLE.md b/.agent-taskgraph/roles/reference-researcher/ROLE.md new file mode 100644 index 00000000..dadd4a9a --- /dev/null +++ b/.agent-taskgraph/roles/reference-researcher/ROLE.md @@ -0,0 +1,17 @@ +# Role: Reference Researcher + +| Field | Value | +|---|---| +| Role ID | reference-researcher | +| Team revision | rev-1 | +| Origin | initial:design-spec-r1/graph-r1 | +| Lifecycle | persistent | +| State | assigned | +| Core responsibility | Evidence-labeled reference runtime census and transferable structural lessons | +| Owned scope | `docs/reference/` | +| Explicitly not responsible | Original product decisions, product/content/presentation files, runtime development, asset reuse | +| Default runtime | codex / gpt-5.6-sol / xhigh / yolo | +| Current Goal | task:ABG-REF-CENSUS | +| Session ID | PENDING | + +Read `.agent-taskgraph/PROJECT.md`, current Goal/context/dispatch, frozen spec and graph node before work. Preserve provenance, do not expose secrets, and do not copy commercial assets into Git. diff --git a/.agent-taskgraph/roles/systems-designer/ROLE.md b/.agent-taskgraph/roles/systems-designer/ROLE.md new file mode 100644 index 00000000..b387f14f --- /dev/null +++ b/.agent-taskgraph/roles/systems-designer/ROLE.md @@ -0,0 +1,17 @@ +# Role: Systems Designer + +| Field | Value | +|---|---| +| Role ID | systems-designer | +| Team revision | rev-1 | +| Origin | initial:design-spec-r1/graph-r1 | +| Lifecycle | persistent | +| State | assigned | +| Core responsibility | Original player contract, battle, professions, skills, economy, balance, failure and save design | +| Owned scope | `docs/product/` | +| Explicitly not responsible | Reference census, named content rows, UI/art production, runtime development | +| Default runtime | codex / gpt-5.6-sol / xhigh / yolo | +| Current Goal | task:ABG-SYSTEM-DESIGN | +| Session ID | PENDING | + +Design state-dependent choices and explicit formulas/boundaries. Do not hide a weak loop with content volume or copy reference expression. diff --git a/.agent-taskgraph/spec.md b/.agent-taskgraph/spec.md new file mode 100644 index 00000000..3a6e07f6 --- /dev/null +++ b/.agent-taskgraph/spec.md @@ -0,0 +1,82 @@ +# Execution Spec: Complete Pre-Production Design Package + +> Status: FROZEN +> Requested: 2026-08-10 / Owner requested a complete original game design before formal development and authorized parallel Agent TaskGraph execution. +> Frozen by: Owner / 2026-08-10 +> Revision: design-spec-r1 + +## Decision This Package Enables + +After reviewing the complete product, content, UI, art, audio, balance and interactive prototype, the Owner can decide whether Aetherbound Guild is ready for a formal vertical-slice implementation Goal. + +## Confirmed Context + +| Type | Fact | Evidence | +|---|---|---| +| Confirmed | The private reference archive contains 1,638 extracted images, 43 AudioClips, 208 AnimationClips and 196 project type records. These are asset/object counts, not exact gameplay-entity counts. | External archive extraction summary and structural audit dated 2026-08-10 | +| Confirmed | Reference lower bounds include at least 13 profession identities, five biome families, equipment, shop, formation, artifacts, skill tree and battle/reward systems. | `STRUCTURAL_CONTENT_COUNT_AUDIT.md` | +| Confirmed | The original game's complete content envelope is 30 characters, 36 professions, 100 enemies, 8 chapters and 320 equipment/items. | Owner decisions in current session | +| Confirmed | Formal runtime development must not begin before complete design review. | Owner instruction and repository `AGENTS.md` | +| Inference | A complete premium strategy campaign can support 25-35 hours when each chapter introduces new interactions rather than only larger values. | Product hypothesis requiring later prototype and playtest validation | +| Unknown | Exact reference totals for recruits, enemies, items, skills, artifacts, formations, achievements and chapters. | `STRUCTURAL_CONTENT_COUNT_AUDIT.md`; resolved as far as observable by ABG-REF-CENSUS | + +## Target Player And Experience + +- Target: strategy/RPG players who enjoy readable party building, equipment synergies, job progression, route planning and watching a prepared plan succeed. +- Session: 8-20 minute expedition segments on mobile/PC/console, with a 25-35 hour first campaign. +- Fantasy: lead a guild that repairs a broken magical network by recruiting distinct adventurers, preparing formations, choosing routes and adapting builds after visible battle outcomes. +- Emotion: anticipation before auto-battle, legible surprise during battle, diagnosis after failure, pride when a prepared synergy works and curiosity about the next region/job branch. + +## Included Scope + +- Product/player contract, pillars, anti-pillars, business model and platform constraints. +- Complete core loop, expedition, battle, intervention, formation, profession, skill, equipment, recruitment, economy, progression, failure/recovery, save, accessibility, localization and postgame contracts. +- Exactly 30 named recruitable characters, 12 base professions, 24 advanced professions, 100 enemy combat identities, 8 chapters and 320 equipment/items. +- At least 120 items that change behavior, targeting, timing, positioning, resources or job identity. +- Complete screen/state inventory including opening, onboarding, guild, roster, character, jobs, equipment, route, battle, intervention, result, failure, recovery, collection, achievements, settings, accessibility, errors, empty states and ending/postgame. +- Art direction, full asset inventory, animation state matrix, VFX language, music plan and SFX event catalog. +- Landscape 16:9 HTML gallery that visually presents every player-facing page and representative chapter state. +- Economy/build simulations, pacing profiles and a no-filler/dominant-strategy audit. +- Interactive design prototype suitable for Owner comprehension review. + +## Excluded Scope + +- Game runtime implementation or engine selection. +- Final production art/audio batches, paid generation beyond separately authorized bounded design comps, voice cloning or video generation. +- Packaging, signing, device installation, TestFlight, stores, publishing or monetization account actions. +- Copying or redistributing reference-game assets, code, formulas, names, prose, layouts or audio. + +## Acceptance Criteria + +- All required documents exist and cross-reference one authoritative content schema. +- Exact content counts pass validators and no content row is a name/number-only filler entry. +- At least 120 equipment rows change behavior and each profession/enemy/chapter has a distinct mechanical role. +- Every screen and meaningful state is represented in the state map and landscape gallery. +- Five player profiles and explicit decision timestamps demonstrate campaign pacing, build counterfactuals, failure/recovery and longest no-decision intervals. +- Independent reviewer finds no unresolved blocker in originality, content completeness, systems coherence, UI comprehension, asset feasibility or simulation. +- Owner can inspect the gallery and interactive prototype; human fun, visual, listening and willingness-to-continue acceptance remain OPEN until Owner review. + +## Hard Frozen Boundaries + +- No runtime code, engine project, package or external publication. +- No third-party commercial reference assets in this Git repository. +- Parallel workers do not modify another worker's owned directory or `.agent-taskgraph/`. +- Product scope/count changes require a spec/graph diff and Owner refreeze. + +## Human Gates + +| Action | Reason | Approver | +|---|---|---| +| Change product/content envelope | Scope and production-cost change | Owner | +| Paid design-comp generation beyond standing task ceiling | External cost | Owner | +| Select engine and begin vertical-slice runtime implementation | Formal development boundary | Owner | +| Delete/replace reference or design authority | Irreversible provenance/history impact | Owner | +| Publish, package or submit | External/release action | Owner | + +## Open Questions + +None. Exact reference content totals are a research deliverable and may remain explicitly `unknown` where the runtime does not expose proof. + +## Freeze Confirmation + +The Owner confirmed the direction, complete content envelope, pre-development completeness requirement, Agent TaskGraph parallelization and Codex runtime profile in the current session on 2026-08-10. diff --git a/.agent-taskgraph/templates/context.md b/.agent-taskgraph/templates/context.md new file mode 100644 index 00000000..99a2aa36 --- /dev/null +++ b/.agent-taskgraph/templates/context.md @@ -0,0 +1,37 @@ +# Context Manifest: <稳定 Task ID> + +> Task ID: `<与 Goal、queue 目录一致>` +> Revision: `<递增整数或内容 hash>` +> Mode: `` +> Budget exception: `` + +## 必须读取（默认不超过 8 项） + +| 路径或稳定引用 | Revision / 范围 | 为什么本 Goal 必须读 | +|---|---|---| +| `.agent-taskgraph/PROJECT.md` | relevant sections | 项目硬约束与运行策略 | +| `.agent-taskgraph/roles//ROLE.md` | current | 职责边界与连续性 | +| `/dispatch.md` | `` | 本次 Role/Session 身份绑定与 ACK 合同 | +| `` | `` | 本次冻结需求 | +| `` | `` | 本节点依赖与路由 | +| `` | current | 单次执行合同 | + +## 按需检索（先搜索，再局部读取） + +| 路径/范围 | 触发条件 | 检索提示 | +|---|---|---| +| `` | 需要确认实现细节时 | `` | +| `.agent-taskgraph/DECISIONS.md` | 命中本模块决策时 | `` | + +## 明确不加载 + +- 无关已完成任务和 archive 全量内容 +- 其他 worker 的完整聊天记录 +- 未被 Goal 引用的长日志、构建产物和大文件 +- `<本任务额外排除项>` + +## 最近 Delta + +| 时间 | 来源 | 新事实/决策/阻塞 | 已落盘到 | 是否需要通知 worker | +|---|---|---|---|---| +| | | | | | diff --git a/.agent-taskgraph/templates/dispatch.md b/.agent-taskgraph/templates/dispatch.md new file mode 100644 index 00000000..768e431d --- /dev/null +++ b/.agent-taskgraph/templates/dispatch.md @@ -0,0 +1,36 @@ +# Dispatch Bootstrap: <稳定 Task ID> + +> PMO 维护。它是 Role 到 Session 的本次绑定合同，不代替 ROLE.md、Goal 或 context.md。 +> 首条消息只发送本文件中的稳定身份与引用，不复制项目背景。每次新建、复用或替换会话都生成新的 Dispatch ID。 + +| 字段 | 值 | +|---|---| +| Task ID | <与 Goal、queue 目录一致> | +| Dispatch ID | :> | +| Role ref | role: | +| Role profile | roles//ROLE.md | +| Role lifecycle | | +| Team revision | <与 ROLES.md、ROLE.md 一致的 rev-N> | +| Goal ref | task: | +| Context manifest | context.md | +| Context revision | <与 Goal、ledger、context.md 一致> | +| Continuity | <新角色 / 复用 session-id / 新会话 + handoff 路径> | +| Session ID | | +| Expected identity ACK | IDENTITY_READY dispatch_id= role=role: team_revision= goal=task: context_revision= | +| Delivery | | +| Identity ACK | | +| ACK evidence | | + +## 启动读取顺序 + +1. `Role profile`：确认长期职责、负责范围、明确不负责和连续性。 +2. `.agent-taskgraph/PROJECT.md` 中与本职责和 Goal 有关的章节。 +3. 当前任务目录的 `context.md`，按其中“必须读取”顺序加载。 +4. 当前唯一 Goal、直接依赖产物和本轮 Delta。 + +## 身份纪律 + +- Role 是长期身份，Session 是可替换容器，Goal 是本次唯一工作授权。 +- worker 首个状态行必须与 `Expected identity ACK` 完全一致；引用缺失、revision 漂移或职责冲突时改报 `IDENTITY_BLOCKED`，不得猜测后开工。 +- 身份确认不授权扩大 Goal、writes、Frozen、权限或 Human Gates。 +- 完成或换会话前把连续性 checkpoint 写回 ROLE.md/handoff；不得把聊天记录当作唯一长期记忆。 diff --git a/.agent-taskgraph/templates/goal.md b/.agent-taskgraph/templates/goal.md new file mode 100644 index 00000000..9ad41c18 --- /dev/null +++ b/.agent-taskgraph/templates/goal.md @@ -0,0 +1,75 @@ +# Goal: <项目/模块> <一句话目标> + +> Stage: <阶段标签>（如 T1 authoring checkpoint / C11E1 implementation） +> Started: <时间> +> Task ID: `<与 graph goal_ref、queue 目录、STATUS 完全一致的稳定 ID>` +> Baseline: ``（B/C/D 类必须可复现且能创建 worktree；无 Git 不得派实现 worker） +> Accepted 上一阶段: ``（上一个 goal 的验收 hash，证据链；首任务可省） +> Frozen spec: ``（只有低风险 A 类快速任务可写“内嵌本 Goal”） +> Graph node: ``（低风险 A 类快速任务写“不适用”） +> Independent contract: ``（额外技术合同；无则写“不适用”） +> Context manifest: `<任务目录内 context.md>`（只列引用和 revision，不复制原文） +> Context revision: `<与 context.md 一致>` +> Legal terminal: **<项目> <目标> candidate ready** 或 **<项目> <目标> redesign required: <最早失败边界>** + +## Objective + +（一段话：只做一件事，做成的样子，精确无歧义。写不清 = 白干一轮） + +## 图输入、输出与写入范围 + +- 直接依赖（needs）： +- 必须读取（consumes）：<上游产物/版本> +- 必须产出（produces）：<给 verifier/下游的产物> +- 唯一写入范围（writes）：<文件/目录/外部资源；不得与并行节点重叠> +- 路由：PASS → ；FAIL → ；最大尝试 + +## 分配记录 + +- Role ref：`role:` +- 角色职责：<引用 ROLE.md 的核心职责 + 本 Goal 为什么属于该职责> +- 角色生命周期： +- 派给：<会话 ID / 岗位名> +- 分配理由：相关性（同模块历史） / 职责匹配（岗位） / 负载均衡 +- 连续性：<新角色 / 复用 session-id / 新会话 + handoff 路径> +- 工作区：（分支：） +- Runtime requested：`runtime=; flavor=; model=<批次确认的准确 id>; effort=<该模型已证明支持的 level>; permission=<准确 mode>; visibility=` +- Runtime observed： +- Runtime verification：<`PENDING` / `VERIFIED`；`pre-dispatch` 或复用时 `pre-redispatch` + 时间> +- Session evidence：<真实会话 ID + PID/线程 ID + 当前 goal_ref + verification ID + 日志/metadata 路径；HAPI 还要引用本任务 runtime-evidence.json 与消息 watermark> +- Dispatch bootstrap：<`dispatch.md`；绑定本 Role/Team revision/Goal/Context revision 的当前身份合同> +- Dispatch message：<`NOT_SENT` / `SENT: <时间 + 通道 + Dispatch ID + 送达证据>`；VERIFIED 前必须为 NOT_SENT> +- Identity ACK：<`PENDING` / `VERIFIED: <完整 IDENTITY_READY 行>`；未匹配不得进入 active> +- 完整启动方式：<可复现命令或控制面动作；不得把请求值写成实际值> + +## 报告协议 + +- 完成 / 失败 / 卡住时通过本 Goal 记录的运行时消息通道通知 PMO（消息含任务号 + 状态 + 一句话结果）；若运行时无消息能力，写完证据后由 PMO 监控循环发现 +- worker 只更新本 Goal/产品 evidence ledger 并提交证据；`.agent-taskgraph/queue/*/ledger.md`、目录状态和 STATUS.md 只能由 PMO 更新 +- **不通知 = 任务未完成**，验收闸不通过 + +## Required State-Dependent Choice（如适用） + +（必须依据状态做选择的决策点——表格式：继承状态 | 条件 | 该选什么。不适用则删本节） + +## 验收标准（证据门） + +- [ ] 验收命令（worker 必须跑并把输出贴回）： +- [ ] 产物路径 / diff 位置： +- [ ] 终态判定：满足全部证据门 → "candidate ready"；任一失败 → 指出最早失败边界 + +## Frozen（禁止触碰，明确列出） + +- 不允许修改的文件/模块： +- 冻结范围（后续阶段/新系统/发布类）： + +## Estimate + +- 实现：Xh / 调试：Xh / 跑测证据：Xh / PMO 审查：30-60m / 硬上限：Xh / 置信度：低中高 + +## 完成时交付 + +- diff 位置 / PR 链接 +- graph 节点约定的 produces 与下游交接版本 +- 验收命令输出（贴回） +- 残余风险 diff --git a/.agent-taskgraph/templates/graph.yaml b/.agent-taskgraph/templates/graph.yaml new file mode 100644 index 00000000..5c6771c5 --- /dev/null +++ b/.agent-taskgraph/templates/graph.yaml @@ -0,0 +1,34 @@ +# 静态任务拓扑。不要在此记录 active/done 等动态状态；动态状态属于 queue + ledger。 +version: 1 +batch: + id: "" + revision: "" + spec: "" + spec_revision: "" + approved_by: "" + approved_at: "" + max_concurrency: 3 + +nodes: + - id: "" + title: "" + kind: "expert|worker|verifier|merge|human_gate" + goal_ref: "task:" + needs: [] + consumes: [] + produces: [] + writes: [] + acceptance: + - "" + on_pass: "" + on_fail: "" + max_attempts: 1 + +# 建图约束： +# - goal_ref 只用稳定 task: 或 decision:；禁止写 queue/inbox、active 等动态路径。 +# - needs 只包含真实数据依赖；下游不读取上游产物就不要画边。 +# - consumes 命中其他节点 produces/writes 时，生产节点必须位于 needs 的祖先链。 +# - 并行节点的 writes 不得重叠；最终整合只能有一个 merge owner。 +# - verifier 使用独立上下文；失败回到最早失败边界对应的最小修复节点。 +# - 每个循环必须有 max_attempts；不可逆动作建 human_gate 节点。 +# - needs/consumes/produces/writes 使用本模板的 JSON-compatible inline list，生成后运行 scripts/validate-graph.py。 diff --git a/.agent-taskgraph/templates/ledger.md b/.agent-taskgraph/templates/ledger.md new file mode 100644 index 00000000..1a74da6c --- /dev/null +++ b/.agent-taskgraph/templates/ledger.md @@ -0,0 +1,47 @@ +# 台账记录：<稳定 Task ID> + +> 每个任务一条记录。状态只有 PMO 能改。文件放在 `queue///ledger.md`。 + +| 字段 | 值 | +|---|---| +| 任务 ID | <与 queue 目录名、graph goal_ref、STATUS 完全一致> | +| Goal ref | task: | +| Goal current path | queue/<当前 state>//goal.md | +| Context manifest | context.md | +| Context revision | <与 context.md 一致的递增整数或内容 hash> | +| Role ref | role: | +| Role lifecycle | | +| Role profile | roles//ROLE.md | +| Role continuity | <新角色 / 复用 session-id / 新会话 + handoff 路径> | +| Reviewer Role ref | > | +| Reviewer Role profile | /ROLE.md> | +| Frozen spec | | +| Graph node | | +| 依赖/路由 | needs: ；PASS → ；FAIL → | +| 状态 | | +| 负责人 | <会话 ID / 岗位名> | +| 分配理由 | 相关性 / 职责匹配 / 负载均衡 | +| 轮次 | 第 1 次（重试 +1） | +| 开始时间 | | +| 最后更新 | | +| 验收结果 | ✅ / ❌（附命令输出） | +| 日志指针 | <当前运行时的会话日志、rollout JSONL、Terminal metadata 或等价证据路径——watch 监视器的输入> | +| Runtime requested | runtime=; flavor=; model=<批次确认且目录中存在的准确 id>; effort=<该模型支持的明确 level>; permission=<准确 mode>; visibility= | +| Runtime observed | runtime=; flavor=; model=; effort=; permission=; visibility= | +| Runtime verification | | +| Session ID | <真实会话/线程 ID；inbox 未创建时写 PENDING> | +| Runtime evidence | | +| Dispatch bootstrap | | +| Dispatch message | | +| Identity ACK | | +| 等待归属 | 在等谁：；等什么：<验收 / 指示 / 外部条件>；静默多久算异常： | + +## 备注 + +（卡住原因、方案变更、Owner 的临时指示等——供复盘的原始记录） + +## 状态转换历史（追加式） + +| 时间 | from → to | 操作者 | 依据/证据 | 唯一下一步 | +|---|---|---|---|---| +| | | PMO | | | diff --git a/.agent-taskgraph/templates/report.md b/.agent-taskgraph/templates/report.md new file mode 100644 index 00000000..848831da --- /dev/null +++ b/.agent-taskgraph/templates/report.md @@ -0,0 +1,30 @@ +# 完成汇报：<任务号> <标题> + +> 一页纸，不要超两屏。Owner 先看摘要，细节保留在 Goal、ledger 与证据中。 +> Frozen spec: | Graph node: + +## 做了什么 + +（2-3 行：改了哪里、怎么实现的） + +## 验收结果 + +| 验收项 | 命令/方法 | 结果 | +|---|---|---| +| … | … | ✅ / ❌ | + +（通过才归档 done/，未通过说明去向：重试中 / failed 待定夺） + +## 风险与发现 + +（worker 和 reviewer 发现的问题、方案偏离、存量 bug——不只是"没问题"） + +## 规格与图一致性 + +- Frozen 范围是否保持：✅ / ❌（偏差说明） +- produces 是否完整交给下游：✅ / ❌ / 不适用 +- 实际路由：PASS → / FAIL → + +## 下一步 + +（合并建议 / 需要的 Owner 决策 / 建议的下一个任务） diff --git a/.agent-taskgraph/templates/role.md b/.agent-taskgraph/templates/role.md new file mode 100644 index 00000000..97c8fab9 --- /dev/null +++ b/.agent-taskgraph/templates/role.md @@ -0,0 +1,42 @@ +# Role: <岗位名称> + +> 这是长期职责身份，不是本次任务说明。本次范围、交付和验收只写入对应 Goal。 + +| 字段 | 值 | +|---|---| +| Role ID | <稳定小写 ID，如 frontend-ui> | +| Team revision | <当前 rev-N> | +| Origin | / staffing:> | +| 名称 | <面向 Owner 的岗位名> | +| 生命周期 | | +| 状态 | | +| 核心职责 | <长期负责什么> | +| 负责范围 | <模块、目录、产物或业务域> | +| 明确不负责 | <职责边界；方案决策和越界修改默认不负责> | +| 默认能力 | <需要的工具、领域知识、测试能力> | +| 默认 Runtime | | +| 当前 Goal | > | +| 当前 Session ID | | +| 连续性记录 | <最近完成的 Goal、关键上下文/handoff 路径；不得只存在聊天记忆> | +| 最后更新 | <时间 + PMO> | + +## 开工必读 + +- `.agent-taskgraph/PROJECT.md` +- 当前冻结 spec、graph 节点、Goal、ledger 与直接依赖产物 +- 与本职责有关的 `DECISIONS.md` 标题和连续性记录 + +## 职责规则 + +- 角色负责长期判断边界，Goal 负责单次授权；角色不能扩大 Goal。 +- 同一 persistent 角色不得并发执行多个 active/review Goal。 +- 同模块串行任务优先复用本角色及其可恢复会话；失败污染、上下文耗尽或隔离要求出现时换会话，但保留同一 Role ID 并写 handoff。 +- 每次新建、复用或替换 Session 都使用当前 Goal 的新 `dispatch.md` 完成 Role/Team/Context 身份 ACK；旧 Goal 的 ACK 不能复用。 +- task-scoped 角色完成后标记 `retired`；persistent 角色完成后回到 `available`。 +- 动态新增、拆分、替换、暂停或退役必须引用 staffing change；不能只改会话名称或聊天称呼。 + +## 连续性历史（追加式） + +| 时间 | Goal | Session ID | 状态变化 | handoff / 证据 | +|---|---|---|---|---| +| | | | | | diff --git a/.agent-taskgraph/templates/spec.md b/.agent-taskgraph/templates/spec.md new file mode 100644 index 00000000..d139dafb --- /dev/null +++ b/.agent-taskgraph/templates/spec.md @@ -0,0 +1,76 @@ +# 执行规格：<批次/目标> + +> Status: DRAFT | FROZEN +> Requested: <时间 / 用户原始请求> +> Frozen by: <用户标识 / 时间；DRAFT 时留空> +> Revision: <版本或 git hash> + +## 原始请求 + +（保留用户原话；一句话可以作为入口，但不能替代下面的执行规格。） + +## 上下文证据 + +| 类型 | 内容 | 证据 | +|---|---|---| +| 已确认 | <从代码、文档、运行结果确认的事实> | <文件:行 / 命令输出 / 截图> | +| 合理推断 | <当前假设> | <推断依据；不得写成事实> | +| 待用户决策 | <无法从项目得出的产品选择> | <推荐默认值及影响> | + +## 目标用户与场景 + +- 目标用户： +- 触发场景： +- 要解决的问题： + +## 目标结果 + +（描述做成后的可观察行为，不写实现方案。） + +## 包含范围 + +- + +## 不做范围 + +- + +## 行为与边界条件 + +| 情况 | 期望行为 | +|---|---| +| 正常路径 | | +| 空/错误/权限状态 | | +| 兼容与回滚 | | + +## 验收标准 + +- [ ] <用户可观察结果> +- [ ] <可运行命令及通过条件> +- [ ] <产物/数据/视觉证据> + +## 硬约束与 Frozen + +- 不允许修改： +- 必须保持： +- 时间/成本/平台约束： + +## Human Gates + +| 动作 | 为什么不可逆或高影响 | 需要谁批准 | +|---|---|---| +| <迁移/删除/权限/合并/发布等> | | | + +## 决策记录 + +| 决策 | 选择 | 理由 | 决策人/时间 | +|---|---|---|---| +| | | | | + +## 开放问题 + +- + +## 冻结确认 + +（PMO 用一页内摘要向用户确认。只有用户明确批准且开放问题为“无”后，才将 Status 改为 FROZEN。后续改变目标、范围、验收、依赖或 Frozen 必须提交 spec/graph diff。） diff --git a/.agent-taskgraph/templates/staffing-change.md b/.agent-taskgraph/templates/staffing-change.md new file mode 100644 index 00000000..90a2bb92 --- /dev/null +++ b/.agent-taskgraph/templates/staffing-change.md @@ -0,0 +1,54 @@ +# Staffing Change: + +> Team revision: `` +> Status: `` +> Type: `` +> Proposed by: `` +> Approved by: `` + +## 触发证据 + +- 当前卡点/职责缺口：<具体证据，不写“可能更快”> +- 受影响 graph 节点和关键路径： +- 为什么现有角色不能串行完成：<边界、负载、独立性或故障证据> +- 不加人的替代方案：<继续串行 / 调整 Goal / 暂停；成本与影响> + +## 变更内容 + +| 动作 | Role ID | 长期职责 | 本次 Goal | writes | 生命周期 | session | model/effort | 权限/可见性 | +|---|---|---|---|---|---|---|---|---| +| | | <职责> | | <范围> | | | <配置> | <配置> | + +## 职责迁移 + +- 原角色保留：<职责和 Goal> +- 转移给新角色：<职责、文件、产物和未决项> +- 明确不再负责：<旧角色释放的边界> +- Handoff： +- 写入冲突检查：<无 / 解决方式> + +## 图、成本与授权影响 + +- Graph diff：<新增/保留/暂停/作废节点及依赖变化> +- Spec 影响：<不改变 Frozen / 需要新 revision 并重新冻结> +- 新增会话与并发：<数量；变更后总数与池上限> +- 预计成本/时间变化：<可用运行时指标；不可用写 unavailable> +- 新权限、依赖或 Human Gate：<无 / 具体变化> + +## 应用事务 + +- [ ] Owner 或精确预授权已确认 +- [ ] 受影响节点已暂停且状态落盘 +- [ ] spec/graph/DECISIONS 已按影响更新并验证 +- [ ] ROLES.md team revision 与 ROLE.md 职责边界已更新 +- [ ] Goal/context/ledger 与 handoff 已更新 +- [ ] 新派发预览已确认 +- [ ] 新 runtime 已完成 task-bearing bootstrap 前验证 +- [ ] STATUS/state validator 已通过 +- [ ] 旧会话/角色已恢复、暂停或退役，无双重 owner + +## 回滚条件与结果 + +- 最早失败边界：<配置不匹配 / handoff 不完整 / 写入冲突 / 无收益等> +- 回滚动作：<停止新会话、恢复旧 owner、回退 graph/role binding> +- 最终结果：