Never edit this file directly. To make additions or modifications, edit the appropriate section in ./vstack.toml. Then run vstack refresh.
Project Management
User-facing wrappers and TPM-execution workflows for project-level planning, audit, roadmap, and research-driven decomposition.
Commands
| Command |
Arguments |
Workflow |
cycle-plan |
— |
workflows/cycle-plan.md |
audit-issues |
project | project "Name" | issue [IDs] | --issues [file] | project-order |
workflows/audit-issues.md |
roadmap plan |
[feature] | [feature] @[research-path] |
workflows/roadmap-plan.md |
roadmap create |
@[plan-file] |
workflows/roadmap-create.md |
research-spike |
— |
workflows/research-spike.md |
research-complete |
[ISSUE_ID] |
workflows/research-complete.md |
research-issue |
— |
workflows/research-issue.md (internal — invoked by research-spike) |
Workflows
User-facing wrappers
| Workflow |
Purpose |
| cycle-plan |
User dialog + Linear actions for cycle planning; delegates analysis to tpm-cycle-plan |
| audit-issues |
User dialog + tracker actions (Linear or GitHub) for issue audits; project/project-order audits are Linear-only; delegates to tpm-audit / tpm-audit-project-order |
| roadmap-plan |
Specialist consultation + research gating; delegates to tpm-roadmap-plan |
| roadmap-create |
Execute a roadmap plan: project + issue creation via audit |
| research-spike |
User-initiated research with consultation, asset prep, and researcher delegation |
| research-complete |
Route a researcher-completed research issue (Targeted / Pervasive / Strategic) |
| research-issue |
Create research issue + assets, then delegate to agent:researcher (called by research-spike) |
TPM-execution (called by the wrappers)
TPM workflows return JSON recommendations only.
| Workflow |
Purpose |
| tpm-cycle-plan |
Analyze backlog, compute architecture order |
| tpm-roadmap-plan |
Cross-project analysis, architecture gaps |
| tpm-audit |
Audit issues/projects for relations, hierarchy |
| tpm-audit-project-order |
Analyze project dependencies and ordering |
Templates
| Template |
Purpose |
| issue-description-template |
Standard markdown for issue descriptions |
| parent-issue-template |
Parent/bundle issues with sub-issue coordination |
Schemas
| Schema |
Purpose |
| audit-issues-input |
Input for issue audit workflows |
| roadmap-plan-input |
Input for roadmap planning |
| cycle-plan-output |
TPM cycle plan output |
| roadmap-plan-output |
TPM roadmap analysis output |
| audit-output |
TPM audit output |
| audit-project-order-output |
TPM project-order audit output |
References
| Topic |
Location |
| Issue creation |
references/issues.md |
| Initiatives & Projects |
references/initiatives-projects.md |
| Dependencies |
references/dependencies.md |
| Prioritization factors |
references/prioritization.md |
| Label management |
references/labels.md |
| Issue tracker CLI |
Companion tracker skills — Linear: .agents/skills/linear/scripts/linear.sh; GitHub: gh + .agents/skills/github/scripts/github.sh |
Execution Rules
- Execute all workflow sections in order. The workflow decides what to skip via "Skip if" conditions — never skip based on your own scope assessment.
<delegation_format> and <output_format> tags are literal templates: fill [PLACEHOLDERS], omit empty lines, add nothing else, do not paraphrase.- When a user-visible
<output_format> report is followed by an Ask user, AskUserQuestion, or question-tool step, send the filled report as a normal assistant message first. Then invoke the question tool separately with only a concise question and concise options; do not paste the report into the question text, option labels, or option descriptions unless a short summary is explicitly requested. This keeps Pi question popups focused on the choice instead of the preceding report.
- Before any issue create or label update, load the live issue-label inventory and project taxonomy, build the full final
labels[] set, and run the label preflight in references/labels.md. Unknown labels, parent/group labels, missing required categories, or exclusivity violations stop the workflow before mutation.
- In multi-issue audits, resolve and retain repository verification context per issue/contract. A PR, branch, or resolved path set associated with one issue must not scope another issue's checks.
- Issue-mode audits resolve tracker context once (audit-issues § 1.2.1) and route every preflight, TPM fetch, and mutation through that tracker. GitHub-tracked audits must not require Linear installation, sync, or authentication; where GitHub lacks a Linear concept, the workflow degrades explicitly (documented note in the audit summary), never silently.
Hierarchy
Initiative → Project → Milestone → Issue → Sub-Issue
| Level |
Duration |
Example |
| Initiative |
Months |
"Platform MVP" |
| Project |
2-6 weeks |
"Phase 1: Foundation" |
| Milestone |
Key checkpoint |
"Data Pipeline Complete", "Alpha" |
| Issue |
1-5 days |
"Implement message queue" |
| Sub-Issue |
Breakdown |
Child issue for parallel work |
Prioritization
Score = (Critical Path x 3) + (Dependencies x 2) + (Risk x 2) + (Value x 1) - (Estimate x 0.5)
Thresholds: 8+ P1 | 5-7 P2 | 3-4 P3 | 0-2 P4
Health Indicators
| Indicator |
Green |
Yellow |
Red |
| Blocked issues |
0 |
1-2 |
3+ |
| In Progress age |
<3 days |
3-7 days |
>7 days |
| Completion ratio (7d) |
>0.8 |
0.5-0.8 |
<0.5 |
Dependencies
- Issue tracker CLI —
linear skill for Linear-tracked work; github skill + gh for GitHub-tracked issue audits
git (repository/change-aware audit verification scope)jq
1---2name: project-management3description: TPM-orchestrated planning, audit, roadmap, and research-driven decomposition. Owns the user-facing wrappers (cycle-plan, audit-issues, roadmap-*, research-*) and the underlying TPM execution workflows.4license: MIT5---67> **Never edit this file directly.** To make additions or modifications, edit the appropriate section in `./vstack.toml`. Then run `vstack refresh`.89# Project Management1011User-facing wrappers and TPM-execution workflows for project-level planning, audit, roadmap, and research-driven decomposition.1213## Commands1415| Command | Arguments | Workflow |16|---------|-----------|----------|17| `cycle-plan` | — | `workflows/cycle-plan.md` |18| `audit-issues` | `project` \| `project "Name"` \| `issue [IDs]` \| `--issues [file]` \| `project-order` | `workflows/audit-issues.md` |19| `roadmap plan` | `[feature]` \| `[feature] @[research-path]` | `workflows/roadmap-plan.md` |20| `roadmap create` | `@[plan-file]` | `workflows/roadmap-create.md` |21| `research-spike` | — | `workflows/research-spike.md` |22| `research-complete` | `[ISSUE_ID]` | `workflows/research-complete.md` |23| `research-issue` | — | `workflows/research-issue.md` (internal — invoked by `research-spike`) |2425## Workflows2627### User-facing wrappers2829| Workflow | Purpose |30|----------|---------|31| [cycle-plan](workflows/cycle-plan.md) | User dialog + Linear actions for cycle planning; delegates analysis to `tpm-cycle-plan` |32| [audit-issues](workflows/audit-issues.md) | User dialog + tracker actions (Linear or GitHub) for issue audits; project/project-order audits are Linear-only; delegates to `tpm-audit` / `tpm-audit-project-order` |33| [roadmap-plan](workflows/roadmap-plan.md) | Specialist consultation + research gating; delegates to `tpm-roadmap-plan` |34| [roadmap-create](workflows/roadmap-create.md) | Execute a roadmap plan: project + issue creation via audit |35| [research-spike](workflows/research-spike.md) | User-initiated research with consultation, asset prep, and researcher delegation |36| [research-complete](workflows/research-complete.md) | Route a researcher-completed research issue (Targeted / Pervasive / Strategic) |37| [research-issue](workflows/research-issue.md) | Create research issue + assets, then delegate to `agent:researcher` (called by `research-spike`) |3839### TPM-execution (called by the wrappers)4041TPM workflows return JSON recommendations only.4243| Workflow | Purpose |44|----------|---------|45| [tpm-cycle-plan](workflows/tpm-cycle-plan.md) | Analyze backlog, compute architecture order |46| [tpm-roadmap-plan](workflows/tpm-roadmap-plan.md) | Cross-project analysis, architecture gaps |47| [tpm-audit](workflows/tpm-audit.md) | Audit issues/projects for relations, hierarchy |48| [tpm-audit-project-order](workflows/tpm-audit-project-order.md) | Analyze project dependencies and ordering |4950## Templates5152| Template | Purpose |53|----------|---------|54| [issue-description-template](templates/issue-description-template.md) | Standard markdown for issue descriptions |55| [parent-issue-template](templates/parent-issue-template.md) | Parent/bundle issues with sub-issue coordination |5657## Schemas5859| Schema | Purpose |60|--------|---------|61| [audit-issues-input](schemas/audit-issues-input.md) | Input for issue audit workflows |62| [roadmap-plan-input](schemas/roadmap-plan-input.md) | Input for roadmap planning |63| [cycle-plan-output](schemas/cycle-plan-output.md) | TPM cycle plan output |64| [roadmap-plan-output](schemas/roadmap-plan-output.md) | TPM roadmap analysis output |65| [audit-output](schemas/audit-output.md) | TPM audit output |66| [audit-project-order-output](schemas/audit-project-order-output.md) | TPM project-order audit output |6768## References6970| Topic | Location |71|-------|----------|72| Issue creation | [references/issues.md](references/issues.md) |73| Initiatives & Projects | [references/initiatives-projects.md](references/initiatives-projects.md) |74| Dependencies | [references/dependencies.md](references/dependencies.md) |75| Prioritization factors | [references/prioritization.md](references/prioritization.md) |76| Label management | [references/labels.md](references/labels.md) |77| Issue tracker CLI | Companion tracker skills — Linear: `.agents/skills/linear/scripts/linear.sh`; GitHub: `gh` + `.agents/skills/github/scripts/github.sh` |7879## Execution Rules8081- Execute all workflow sections in order. The workflow decides what to skip via "**Skip if**" conditions — never skip based on your own scope assessment.82- `<delegation_format>` and `<output_format>` tags are literal templates: fill `[PLACEHOLDERS]`, omit empty lines, add nothing else, do not paraphrase.83- When a user-visible `<output_format>` report is followed by an `Ask user`, `AskUserQuestion`, or question-tool step, send the filled report as a normal assistant message first. Then invoke the question tool separately with only a concise question and concise options; do not paste the report into the question text, option labels, or option descriptions unless a short summary is explicitly requested. This keeps Pi question popups focused on the choice instead of the preceding report.84- Before any issue create or label update, load the live issue-label inventory and project taxonomy, build the full final `labels[]` set, and run the label preflight in `references/labels.md`. Unknown labels, parent/group labels, missing required categories, or exclusivity violations stop the workflow before mutation.85- In multi-issue audits, resolve and retain repository verification context per issue/contract. A PR, branch, or resolved path set associated with one issue must not scope another issue's checks.86- Issue-mode audits resolve tracker context once (audit-issues § 1.2.1) and route every preflight, TPM fetch, and mutation through that tracker. GitHub-tracked audits must not require Linear installation, sync, or authentication; where GitHub lacks a Linear concept, the workflow degrades explicitly (documented note in the audit summary), never silently.8788## Hierarchy8990```91Initiative → Project → Milestone → Issue → Sub-Issue92```9394| Level | Duration | Example |95|-------|----------|---------|96| Initiative | Months | "Platform MVP" |97| Project | 2-6 weeks | "Phase 1: Foundation" |98| Milestone | Key checkpoint | "Data Pipeline Complete", "Alpha" |99| Issue | 1-5 days | "Implement message queue" |100| Sub-Issue | Breakdown | Child issue for parallel work |101102## Prioritization103104```105Score = (Critical Path x 3) + (Dependencies x 2) + (Risk x 2) + (Value x 1) - (Estimate x 0.5)106```107108**Thresholds**: 8+ P1 | 5-7 P2 | 3-4 P3 | 0-2 P4109110## Health Indicators111112| Indicator | Green | Yellow | Red |113|-----------|-------|--------|-----|114| Blocked issues | 0 | 1-2 | 3+ |115| In Progress age | <3 days | 3-7 days | >7 days |116| Completion ratio (7d) | >0.8 | 0.5-0.8 | <0.5 |117118## Dependencies119120- Issue tracker CLI — `linear` skill for Linear-tracked work; `github` skill + `gh` for GitHub-tracked issue audits121- `git` (repository/change-aware audit verification scope)122- `jq`
zenobi-us