| name | project-workflow |
| description | Universal project workflow — brainstorming, documentation, task planning, and implementation. Works with GitHub and GitLab. Use when starting a new project, discussing a feature, updating project docs, decomposing work into issues, or implementing tasks from a backlog. Triggers on "project workflow", "start project", "update docs", "create issues", "implement task", "take issue", "work on feature", or when the user wants end-to-end project support at any stage. |
Project Workflow
End-to-end skill for software projects — from first idea to shipped feature. Works at any project stage with GitHub or GitLab.
How Phases Work
All four phases are independently enterable at any time. Sequential order is a recommendation for new projects — not a constraint.
The user can jump to any phase at any moment:
- discussed a feature in chat → go straight to Phase 3 to create issues
- backlog exists → go straight to Phase 4 to implement
- docs are stale → go straight to Phase 2 to update them
- idea needs thinking through → go to Phase 1 even mid-project
Sequential flow is the default only when starting a greenfield project or when the user explicitly says to go step by step. In all other cases, go directly to the requested phase.
Entry Point
Read the repository state first, then pick the phase based on the user's explicit request — or, if none, based on context signals below.
User's explicit request always takes priority over context signals.
| Signal | Phase |
|---|
| "brainstorm / discuss / think through / let's explore" | 1 — Brainstorm |
| "update docs / update README / fix documentation" | 2 — Docs |
| "create issues / decompose / plan / add to backlog" | 3 — Planning |
| "implement / execute / take issue / issue #N" | 4 — Implementation |
| Empty repo, user wants to explore an idea (no explicit phase) | 1 — Brainstorm |
Code exists but .docs/ is missing or incomplete (no explicit phase) | 2 — Docs |
.docs/ exists, no issues in tracker yet (no explicit phase) | 3 — Planning |
| Backlog exists, user wants to build (no explicit phase) | 4 — Implementation |
If context is still ambiguous, ask once before proceeding.
Sequential Flow (New Project or Feature)
When starting from scratch — or when the user wants to go step by step — run phases in natural order:
Phase 1 → Phase 2 → Phase 3 → Phase 4
Each phase produces artifacts that feed the next:
- Phase 1 outputs: validated concept, requirements, design decisions
- Phase 2 outputs:
.docs/ files, README.md
- Phase 3 outputs: issues with milestones and dependency graph
- Phase 4 outputs: branches, pull/merge requests, merged features
After completing a phase, suggest the next one — but do not force it. The user decides whether to continue or stop.
Orientation Before Any Phase
Before entering any phase, orient yourself:
- Check for
.docs/ — read project-overview.md → prd.md → technical-design.md if present.
- Read
README.md if present.
- Check issue tracker for open issues, milestones, and blockers.
- Use whatever is found as context. Do not re-run earlier phases unless the user asks.
Platform Detection
Detect the hosting platform from git remotes:
git remote -v
- Remote contains
github.com → GitHub. CLI: gh. Read platforms/github.md before running any platform-specific commands.
- Remote contains
gitlab.com or a known GitLab host → GitLab. CLI: glab. Read platforms/gitlab.md before running any platform-specific commands.
Read only the file that matches the detected platform. Do not load both.
Always discover command syntax at runtime via <cli> <command> --help. Do not rely on memorized flags.
Phases
Read the relevant phase file when entering that phase:
