project-roadmap · v1.0.0 · 2026-08-10 · sha256 03ae429f59894458
project-roadmap v1.0.0A
Immutable. This exact content is served forever at /api/v1/blob/03ae429f59894458.
--- name: project-roadmap description: Analyze the current Pulse Coder project/repository and turn vague or concrete needs into prioritized requirements, milestones, tasks, validation plans, and execution handoff. Use when user asks “分析当前项目”, “后续需求推进”, “项目规划”, “下一步做什么”, “roadmap”, “需求拆解”, “排期”, or wants a project health check plus delivery plan. version: 1.0.0 author: Pulse Coder Team --- # Project Roadmap Skill — 项目分析与需求推进 ## Goal Use this skill to analyze the current project/repository and convert product or engineering needs into an actionable delivery plan. The expected outcome is **not just a summary**. It must produce: 1. Current-state project map. 2. Evidence-backed diagnosis. 3. Requirement clarification and decomposition. 4. Prioritized roadmap. 5. Milestone/task plan with validation gates. 6. Clear next action for the agent or human team. --- ## Trigger Examples Use this skill when the user says things like: - “帮我分析当前项目，并安排后续需求推进” - “看一下这个项目现在该做什么” - “给这个需求做拆解和排期” - “帮我规划下一阶段 roadmap” - “项目体检一下，列出优先级” - “analyze this repo and propose next milestones” --- ## Non-Negotiable Rules 1. **Evidence first.** Project claims must come from files, commands, docs, tests, git history, or explicit user input. If not verified, mark as `Assumption`. 2. **Protect user work.** Always inspect `git status --short` before proposing or making code changes. Never overwrite uncommitted user changes unless explicitly instructed. 3. **Separate planning from implementation.** - Analysis and planning may proceed directly. - Code changes, deletions, migrations, production operations, and dependency updates require explicit scope clarity. If the user only asked for planning, do not implement. 4. **Ask only high-leverage questions.** If critical information is missing, ask at most 3 focused questions. Otherwise proceed with stated assumptions. 5. **Make requirements testable.** Every proposed requirement must include acceptance criteria or a measurable success signal. 6. **Prefer small safe increments.** Break work into reviewable PR-sized slices. Avoid giant “rewrite everything” plans unless the repo evidence makes it unavoidable. 7. **Keep one active execution thread.** For multi-step work, use task tracking: list/create/update tasks, keep one main task `in_progress`, mark blockers clearly. --- ## Current Project Profile: Pulse Coder When operating in this repository, treat the project as a TypeScript `pnpm` monorepo. ### Key Workspaces | Path | Role | |---|---| | `packages/engine` | Core agent engine: loop, tools, context, plugins, built-in skill/task/tool-search systems. | | `packages/cli` | Interactive terminal CLI built on `pulse-coder-engine`. | | `packages/cli` (src/tools/sandbox) | Sandboxed JavaScript runtime backing the `run_js` tool. | | `packages/plugin-kit` (src/memory) | Memory integration/service module (`pulse-coder-plugin-kit/memory`). | | `packages/plugin-kit` | Runtime plugin toolkit, including worktree/vault/devtools helpers. | | `packages/acp` | ACP client/runner integration. | | `packages/engine` (src/orchestrator) | Multi-agent orchestration module (subpath export `pulse-coder-engine/orchestrator`). | | `packages/agent-teams` | Multi-session collaborative agent coordination. | | `packages/canvas-cli` | Pulse Canvas CLI and bundled canvas skills. | | `apps/remote-server` | HTTP/webhook runtime for Feishu/Discord and internal agent API. | | `apps/canvas-workspace` | Electron canvas workbench. | ### Important Runtime Notes - Source lives in each workspace’s `src/`; build output goes to `dist/`. - Root commands: - `pnpm run build` - `pnpm test` - `pnpm run dev` - `pnpm start` - Useful targeted checks: - `pnpm --filter pulse-coder-engine typecheck` - `pnpm --filter pulse-coder-engine test` - `pnpm --filter pulse-coder-cli test` - `pnpm --filter @pulse-coder/remote-server build` - `apps/remote-server` is the webhook/server runtime. Its key files include: - `src/index.ts` - `src/server.ts` - `src/core/dispatcher.ts` - `src/core/agent-runner.ts` - `src/core/engine-singleton.ts` - `src/routes/internal.ts` - Skill files use `.pulse-coder/skills/<skill-name>/SKILL.md` with YAML frontmatter. ### Common Feature Areas | Need type | Start investigation here | |---|---| | Agent loop behavior | `packages/engine/src/core/loop.ts`, `packages/engine/src/context/`, `packages/engine/src/ai/` | | Built-in tools | `packages/engine/src/tools/` | | Plugin loading/hooks | `packages/engine/src/plugin/`, `packages/engine/src/built-in/` | | Skills system | `packages/engine/src/built-in/skills-plugin/`, `.pulse-coder/skills/` | | Task tracking | `packages/engine/src/built-in/task-tracking-plugin/` | | Tool search/deferred tools | `packages/engine/src/built-in/tool-search-plugin/`, remote tool registration | | CLI UX | `packages/cli/src/` | | Remote Discord/Feishu runtime | `apps/remote-server/src/core/`, `apps/remote-server/src/platforms/`, `apps/remote-server/src/routes/` | | Internal scheduled runs | `apps/remote-server/src/routes/internal.ts`, cron-related tools/routes | | Memory | `packages/plugin-kit/src/memory/`, `apps/remote-server/src/core/memory-integration.ts` | | Worktree/vault binding | `packages/plugin-kit/`, `apps/remote-server/src/core/worktree/` | | Canvas workbench | `apps/canvas-workspace/`, `docs/canvas-workspace-product/`, `docs/06-harness-engineering-roadmap.md` | --- ## Required Workflow ### Phase 0 — Scope Alignment Identify the user’s intent: | User intent | Deliverable | |---|---| | “分析当前项目” | Project map + health diagnosis + risks + immediate next steps. | | “需求推进” | Requirement decomposition + priority + milestone plan + task board. | | “做某个功能” | PRD-lite + technical plan + implementation slices + validation plan. | | “排期/roadmap” | Sequenced roadmap with dependencies, owners/roles, confidence, and risks. | | “直接干” | Create execution tasks, inspect repo, implement only after scope is clear. | If the user does not specify a target area, default to **repo-wide analysis plus next 2–4 week plan**. Ask up to 3 questions only if needed: 1. What is the target audience/user or business goal? 2. What timeframe or release deadline matters? 3. Are we planning only, or should we also implement the first slice? If unanswered, continue with assumptions. --- ### Phase 1 — Repository Discovery Run or inspect, as appropriate: 1. `pwd`, `git status --short`, `git branch --show-current`. 2. Workspace manifests: - `package.json` - `pnpm-workspace.yaml` - each relevant workspace `package.json` 3. Project guidance: - `README.md`, `README-CN.md` - `AGENTS.md`, `CLAUDE.md` - `docs/`, `architecture/` 4. Source topology: - top-level `packages/*/src` - top-level `apps/*/src` 5. Existing tests and scripts: - `*.test.ts`, `*.spec.ts` - package `scripts` 6. Recent work context when useful: - `git diff --stat` - `git log --oneline -10` Do not read huge generated folders such as `dist/`, `node_modules/`, release outputs, session stores, or private memory data unless directly relevant. --- ### Phase 2 — Project Map Produce a concise system map: 1. **What the product is** — one paragraph. 2. **Architecture layers** — runtime, tools, plugins, clients/apps, storage/integration. 3. **Key modules and ownership boundaries**. 4. **Primary data/control flows**, for example: - user input → platform/CLI → dispatcher/runner → engine loop → tools/plugins → response streaming - skill loading → registry → `skill` tool → detailed instructions 5. **Operational entrypoints** and important commands. 6. **Known docs vs code mismatches** if any. Mark each claim as: - `Fact` — verified from repo evidence. - `Inference` — reasoned from evidence. - `Assumption` — not verified. --- ### Phase 3 — Health Diagnosis Assess the project across these dimensions: | Dimension | Checkpoints | |---|---| | Product clarity | Who is the user? What job-to-be-done? What is the current wedge? | | Architecture | Boundaries, dependency direction, plugin extensibility, runtime coupling. | | Code quality | Type strictness, duplication, naming, local complexity, generated artifacts. | | Testability | Existing tests, critical paths covered, missing integration/e2e tests. | | Developer experience | Build scripts, targeted commands, docs, setup friction. | | Runtime reliability | retries, abort, compaction, tool failure handling, state persistence. | | Security | secrets handling, internal API protection, path/file operations, webhook verification. | | Observability | logs, run IDs, latency traces, devtools, Langfuse/plugin hooks. | | Delivery risk | blockers, unclear requirements, migrations, third-party APIs, platform quirks. | Use severity: - `P0` — blocks correctness/security/release. - `P1` — important for near-term delivery. - `P2` — improves maintainability or UX. - `P3` — future optimization. --- ### Phase 4 — Requirement Intake and Decomposition For each need, create a PRD-lite block: ```md ## Requirement: <name> - Problem: - Target user / scenario: - Desired outcome: - Non-goals: - Constraints: - Acceptance criteria: 1. ... 2. ... - Success metrics: - Dependencies: - Risks: - Open questions: ``` Then decompose into engineering slices: ```md ### Slice <N>: <small deliverable> - Scope: - Files likely touched: - Implementation notes: - Tests: - Docs/ops updates: - Rollback plan: - Definition of Done: ``` Slices should usually fit in one focused PR/MR. --- ### Phase 5 — Prioritization Use a lightweight scoring model unless the user provides another one. Score each candidate 1–5: | Factor | Meaning | |---|---| | Impact | User/business value if completed. | | Urgency | Time sensitivity or blocking nature. | | Confidence | Evidence quality and requirement clarity. | | Effort inverse | 5 = small/easy, 1 = large/uncertain. | | Risk reduction | How much this reduces future delivery risk. | Suggested priority score: ```text Priority = Impact + Urgency + Confidence + EffortInverse + RiskReduction ``` Then classify: - `Now / P0`: must do immediately. - `Next / P1`: next milestone. - `Later / P2`: valuable but not blocking. - `Park / P3`: explicitly defer. Also identify dependencies: “A must happen before B because …”. --- ### Phase 6 — Roadmap and Execution Plan Produce a roadmap at three resolutions: 1. **This week** — concrete tasks, validation, expected outputs. 2. **Next 2–4 weeks** — milestone sequence and dependencies. 3. **Later** — strategic backlog and unknowns to resolve. Each milestone must include: ```md ## Milestone <name> - Goal: - User-visible outcome: - Work slices: - Validation plan: - Release/rollback notes: - Risks and mitigations: - Exit criteria: ``` For implementation handoff, create a task plan: ```md | Task | Priority | Owner/Agent | Dependencies | Validation | Status | |---|---:|---|---|---|---| ``` If task-tracking tools are available, create/update tasks for accepted execution work. --- ### Phase 7 — Validation Gates Every plan must include validation commands or checks. For this repo, prefer targeted checks: | Area | Suggested checks | |---|---| | Engine loop/tools/plugins | `pnpm --filter pulse-coder-engine test`; `pnpm --filter pulse-coder-engine typecheck` | | CLI | `pnpm --filter pulse-coder-cli test`; `pnpm --filter pulse-coder-cli build` | | Sandbox | `pnpm --filter pulse-coder-cli test` (sandbox specs live in src/tools/sandbox) | | Memory | `pnpm --filter pulse-coder-plugin-kit test`; `pnpm --filter pulse-coder-plugin-kit build` | | Remote server | `pnpm --filter @pulse-coder/remote-server build` | | Cross-package change | `pnpm run build`; targeted tests first, full build last | | Docs/skill-only change | parse/read file, check frontmatter has `name` and `description`; no build required unless loader changed | If validation cannot run, state why and provide the next best evidence. --- ## Required Output Format Use this structure by default: ```md # 项目分析与需求推进方案 ## 1. 结论先行 - 当前判断： - 最应该做的 3 件事： - 最大风险： ## 2. 证据来源 | Evidence | Path/Command | What it supports | Confidence | |---|---|---|---| ## 3. 当前项目地图 - 产品定位： - 架构层次： - 关键模块： - 主要流程： ## 4. 健康诊断 | Area | Finding | Severity | Evidence | Recommendation | |---|---|---:|---|---| ## 5. 需求拆解 <PRD-lite blocks> ## 6. 优先级排序 | Candidate | Impact | Urgency | Confidence | EffortInverse | RiskReduction | Priority | Tier | |---|---:|---:|---:|---:|---:|---:|---| ## 7. Roadmap ### This week ### Next 2–4 weeks ### Later ## 8. 执行任务板 | Task | Priority | Dependencies | Validation | Status | |---|---:|---|---|---| ## 9. 开放问题与决策点 - Decision needed: - Assumption to verify: ## 10. 下一步 - Recommended immediate next action: - If you want me to execute: <specific first slice> ``` --- ## Quality Checklist Before finalizing, verify: - [ ] `git status --short` was checked or explicitly unnecessary. - [ ] Claims are tied to evidence or marked as assumptions. - [ ] Requirements have acceptance criteria. - [ ] Priorities explain tradeoffs, not just labels. - [ ] Roadmap includes dependencies and risks. - [ ] Execution tasks are small enough for PR-sized work. - [ ] Validation commands/checks are listed. - [ ] User work and secrets are protected. --- ## Completion Criteria This skill is complete when the user receives either: 1. A repo-wide project analysis plus prioritized roadmap, or 2. A focused requirement plan with task-level execution handoff, or 3. A clear blocker report explaining what information is missing and the minimum questions needed to proceed.