project-roadmap

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

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

Required Workflow

Phase 0 — Scope Alignment

Identify the user’s intent:

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:

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:

## 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:

### 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:

Suggested priority score:

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:

## 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:

| 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:

If validation cannot run, state why and provide the next best evidence.

Required Output Format

Use this structure by default:

# 项目分析与需求推进方案

## 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.