Skip to content

vt-c-0-start

Start here! Shows the complete development workflow and validates your project is ready to begin. Use this when starting a new project or to see the recommended workflow sequence.

Plugin: core-standards
Category: Development Workflow
Command: /vt-c-0-start

Phase 0: Start - Workflow Overview

Welcome to the VisiTrans Development Workflow. This command shows you the complete development lifecycle and validates your project is ready.

The Workflow Sequence

┌─────────────────────────────────────────────────────────────────┐
│                    DEVELOPMENT WORKFLOW                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   /vt-c-0-start     You are here - Overview & validation             │
│       │                                                          │
│       ▼                                                          │
│   /vt-c-1-bootstrap  Scaffold project structure                       │
│       │                                                          │
│       ▼                                                          │
│   /vt-c-2-plan      Design & architecture (conceptual-orchestrator)   │
│       │                                                          │
│       ▼                                                          │
│   /vt-c-3-build     Implementation with /vt-c-journal captures             │
│       │                                                          │
│       ▼                                                          │
│   /vt-c-4-review    Code review (implementation-orchestrator)         │
│       │                                                          │
│       ▼                                                          │
│   /vt-c-5-finalize    Pre-merge checks (finalization-orchestrator)   │
│       │                                                          │
│       ▼                                                          │
│   /vt-c-6-operate   Production: bugfix & incident response            │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Execution Instructions

When this skill is invoked, follow these steps:

Step 0: Ensure Feature Branch

Before any work begins, check the git branch:

  1. Check if this is a git repository: git rev-parse --is-inside-work-tree 2>/dev/null

  2. If NOT a git repo → skip this step

  3. Check current branch: git branch --show-current

  4. If on main or master → create a feature branch before proceeding

  5. If already on a feature branch → confirm and continue

  6. If branch creation needed, use AskUserQuestion:

  7. Suggest a branch name based on the task: feature/[feature-name]
  8. Let the user choose or provide their own name

  9. Create and checkout: git checkout -b [branch-name]

  10. Display: 

    Branch: [branch-name]
All changes will be committed to this branch.

Step 0.5: Project Registration Check

  1. Read TOOLKIT_ROOT/intake/projects.yaml (resolve TOOLKIT_ROOT from this skill's base directory)
  2. Check if the current working directory appears in the projects list
  3. If NOT registered and the project has a CLAUDE.md or .design-state.yaml:
  4. Ask: "This project is not registered in the toolkit. Register now to enable cross-project scanning and journal aggregation?"
  5. Options: Register now (invoke /vt-c-project-register) | Skip for now
  6. If registered: continue silently

Step 1: Display the Workflow Overview

Show the user the complete workflow diagram above. Explain: - Each phase builds on the previous - Use /vt-c-journal continuously during /vt-c-3-build to capture decisions - Use /vt-c-consolidate periodically to update specs and ADRs

Step 1.5: Ensure Inbox Exists

If this is a git repository and NO inbox folder exists:

  1. Check for existing inbox in this priority order: 00-inbox/, 01-docs/01-inbox/, docs/inbox/, docs/00-inbox/
  2. If NONE found:
  3. Create 00-inbox/README.md using the template from TOOLKIT_ROOT/templates/scaffold/base/inbox-README.md
  4. Display: "Created 00-inbox/. Drop any reference documents here before running bootstrap."
  5. If any inbox found: skip silently

Step 2: Check Project Prerequisites

Scan the current directory for:

  1. PRD.md or PRD document - Product Requirements Document

  2. If missing: "No PRD.md found. Create a PRD with your product vision before proceeding."

  3. CLAUDE.md - Project instructions

  4. If missing but PRD exists: "PRD found but no CLAUDE.md. Run /vt-c-1-bootstrap to create project structure."

  5. If exists: "Project already bootstrapped."

  6. Existing project structure - Check for src/, tests/, etc.

  7. If exists with CLAUDE.md: "Project structure exists. You can proceed to /vt-c-2-plan for new features."

  8. SpecKit Setup - Check for .specify/ directory

  9. If .specify/memory/constitution.md exists: "✓ SpecKit detected. Constitution and specs will guide the workflow."
  10. If any specs/*/state.yaml has status: in_progress: "✓ Active spec detected (derived from branch). Spec-driven development active."

  11. If NO .specify/: "No SpecKit setup found. For spec-driven development (recommended), run /vt-c-specify-and-validate after bootstrap."

  12. Unified Repo Governance - Check for .repo-manifest.yaml

  13. If exists: Run /vt-c-repo-health inline and display the traffic-light summary
  14. Show active specs (derived from branch name) and progress aggregated from per-spec specs/*/state.yaml files
  15. If RED violations: "⚠ Governance violations detected. Run /vt-c-repo-audit --fix"

  16. If not present: skip (governance not active)

  17. User Documentation - Check for docs/user-manual/ directory

  18. If docs/user-manual/mkdocs.yml exists: "✓ User documentation site detected. Docs will be updated during build and validated during review."

  19. If NOT present: "No user documentation setup. If this project needs end-user docs, /vt-c-1-bootstrap can scaffold an MkDocs site."

  20. Beads Issue Tracker - Check for .beads/ directory

  21. If .beads/issues.jsonl exists: "✓ Beads issue tracker active. Cross-session issue tracking with dependency-aware work detection enabled."

  22. If NOT present: "No issue tracker setup. For persistent cross-session task tracking, /vt-c-1-bootstrap can initialize Beads."

  23. Inbox - Check for 00-inbox/ directory

  24. If 00-inbox/ exists with files (excluding README.md, .gitkeep): "✓ Inbox contains [N] documents. These will be used as context during bootstrap."
  25. If 00-inbox/ exists but empty: (silent)

  26. If legacy path detected (01-docs/01-inbox/, docs/inbox/, docs/00-inbox/): "Inbox detected at [path]. Standard location is 00-inbox/ at project root."

  27. Branch Hygiene - Check for stale branches merged into main

Run silently: 

STALE_LOCAL=$(git branch --merged main 2>/dev/null | grep -v '^\*' | grep -v '^\s*main$' | grep -v '^\s*master$' | wc -l | tr -d ' ')
STALE_REMOTE=$(git branch -r --merged main 2>/dev/null | grep -v '^\s*origin/main$' | grep -v '^\s*origin/master$' | grep -v 'HEAD' | wc -l | tr -d ' ')

If STALE_LOCAL > 0 or STALE_REMOTE > 0: 

Branch hygiene:
  Local branches merged but not deleted: [STALE_LOCAL]
  Remote branches merged but not deleted: [STALE_REMOTE]

  Clean up with:
    git branch --merged main | grep -v '^\*' | grep -v '^\s*main$' | xargs git branch -d
    git fetch --prune

If both are 0: skip silently (no output).

Step 3: Provide Recommendations

Based on what was found:

Scenario A: Empty directory 

You're starting fresh!

Created: 00-inbox/ — drop any reference documents here
(meeting notes, requirements, stakeholder feedback, API docs).

Next step: Create your PRD.md or run /vt-c-1-bootstrap
Inbox documents will be used as context during bootstrap.

Scenario B: PRD exists, no structure 

PRD found: PRD.md

Tip: Drop reference documents in 00-inbox/ before running bootstrap.
They'll inform the generated PRD, CLAUDE.md, and README.

Next step: /vt-c-1-bootstrap [project-type] [project-name]

Project types available:
- typescript-api
- typescript-cli
- rails-api
- rails-full
- react-app
- nextjs-app

After bootstrap, consider spec-driven development:
→ /vt-c-specify-and-validate (creates constitution and specs)

Scenario C: Project already bootstrapped 

Project ready!

Current status:
- PRD: Found
- CLAUDE.md: Found
- Structure: Complete
- SpecKit: [Found/Not found]

If SpecKit found:
  → /vt-c-2-plan "Your feature" (spec-aware planning)

If SpecKit NOT found (recommended for production apps):
  → /vt-c-specify-and-validate (creates constitution + specs)
  → Then /vt-c-2-plan "Your feature"

If this project serves end users, consider adding user documentation:
  → /vt-c-1-bootstrap --docs (scaffolds a docs/user-manual/ MkDocs site)

Scenario D: Existing project, adding toolkit 

Existing project detected.

To add toolkit integration:
1. Run /vt-c-1-bootstrap in this directory (will preserve existing files)
2. Or manually create docs/solutions/, docs/vt-c-journal/

If this project serves end users, consider adding user documentation:
  → /vt-c-1-bootstrap --docs (scaffolds a docs/user-manual/ MkDocs site)

Then proceed to: /vt-c-2-plan

Step 4: Show Quick Reference

Quick Reference:
─────────────────────────────────────────────
/vt-c-0-start      → This overview
/vt-c-1-bootstrap  → Create project structure
/vt-c-2-plan       → Architecture & design
/vt-c-3-build      → Implementation guidance
/vt-c-4-review     → Code quality review
/vt-c-5-finalize     → Pre-merge checks
/vt-c-6-operate    → Bugfix & incidents
─────────────────────────────────────────────

Spec-Driven Development (Recommended):
/vt-c-specify-and-validate → Create constitution + specs
                        (run after /vt-c-1-bootstrap)
─────────────────────────────────────────────

Supporting commands:
/vt-c-journal      → Capture learnings (use during /vt-c-3-build)
/vt-c-consolidate  → Update specs/ADRs from journal
/vt-c-commit       → Commit with security checks

Step 5: Offer Next Action

Based on the project state, offer to run the appropriate next command:

"Would you like me to run /vt-c-1-bootstrap now?" (if applicable)

or

"Would you like me to run /vt-c-2-plan for a specific feature?" (if project exists)