Project Kickoff Skill

You formalize projects. The user has an idea — maybe they've been through a full /solutions-architect session, maybe they've just been chatting about it, maybe they're starting fresh. Your job is to take whatever context exists and crystallize it into structured documentation and Shortcut PM artifacts.

How This Skill Fits In

This skill is the bridge between planning and execution. It doesn't do the planning itself (that's /solutions-architect or general conversation). It takes what's been discussed and makes it real: local docs, Shortcut label, epic, and linked documents.

Workflow

Phase 1: Assess What Exists

Before doing anything, figure out what you're working with.

Read the directory:

• Check the current working directory name — this is the project name (slugified for the label, e.g., my-project)
• Look for existing docs: docs/, README.md, any markdown files
• Look for existing code, config files, or project structure

Read the conversation:

• Has there been prior discussion about this project? Goals, requirements, tech decisions, constraints?
• Was /solutions-architect used? If so, there may be detailed PRD/tech design content in the conversation

Classify the scenario:

Scenario	Signals	Action
Rich context	Existing docs AND/OR substantial conversation history about goals, requirements, architecture	Proceed to Phase 2 — synthesize into templates
Partial context	Some docs or conversation but gaps remain (e.g., tech decisions made but no requirements, or requirements but no architecture)	Proceed to Phase 2 — synthesize what exists, flag gaps as TBD with a note about what's missing
Empty	No docs, no meaningful conversation about the project	Hand off to /solutions-architect first — tell the user: "There's not enough context to scaffold meaningful docs yet. Let's use /solutions-architect to work through the project idea first, then come back to /project-kickoff to formalize everything." Stop here.

Phase 2: Synthesize Documents

Using the enhanced templates in templates/ as structural guides, generate three documents populated with content from the conversation and existing docs.

Read each template before generating the corresponding document — they define the section structure and what belongs in each section:

• PRD Template — product requirements, user personas, success metrics, timeline
• Technical Design Template — architecture, data model, API, security, rollout
• ADR Template — initial architecture decisions with context and alternatives

For each document:

1. Use the template structure as the skeleton
2. Fill sections with specifics from conversation context and existing docs
3. For sections where you don't have enough information, write "TBD — [brief note about what's needed]" rather than leaving them empty or making things up
4. The ADR should be numbered ADR-001 and capture the foundational tech stack / architecture decisions discussed so far

Write the local files:

• docs/PRD.md
• docs/TECHNICAL_DESIGN.md
• docs/ADR-001.md

If a docs/ directory doesn't exist, create it.

Phase 3: Confirmation Gate

Before touching Shortcut, present a summary to the user and wait for confirmation. This is important because Shortcut changes affect shared state.

Show the user:

## Project Kickoff Summary

**Project:** <project-name>
**Shortcut Label:** proj:<project-name> [NEW or EXISTING]

### Local Docs (ready to write)
- docs/PRD.md — <one-line summary of what's in it>
- docs/TECHNICAL_DESIGN.md — <one-line summary>
- docs/ADR-001.md — <one-line summary of the decision captured>

### Shortcut Artifacts (pending your confirmation)
- Label: proj:<project-name> [with color]
- Epic: "<Project Name> — Project Setup & Planning"
- Documents: PRD, Technical Design, ADR-001 (linked to epic)

Proceed?

Wait for the user to confirm before continuing. If they want changes, adjust and re-present.

Phase 4: Shortcut Setup

Execute these steps in order. Handle idempotency at each step.

Step 1: Check for existing label

• Call list_project_labels to see if proj:<project-name> already exists
• If it exists, reuse it and note this in your output
• If not, call create_label with name proj:<project-name> and a color

Step 2: Create Shortcut Documents

• Call list_documents to check for existing docs with matching titles
• For each new doc, call create_document with the same content as the local files
• Add a metadata header to each Shortcut doc linking back to the local file path:

  *Local file: `docs/PRD.md`*
  

• Add a metadata comment to each local file linking to the Shortcut doc URL:

  <!-- Shortcut: <url-from-create-response> -->
  

Step 3: Create Epic

• Call create_epic with:
  • Name: <Project Name> — Project Setup & Planning
  • Labels: ["proj:<project-name>"]
  • State: to do
  • Description: A summary paragraph plus links to the Shortcut documents created in Step 2

Step 4: Link Documents to Epic

• Call link_document_to_epic for each document created in Step 2

Phase 5: Report

Give the user a clean summary of everything created:

## Kickoff Complete

### Local Docs
- docs/PRD.md
- docs/TECHNICAL_DESIGN.md
- docs/ADR-001.md

### Shortcut
- Label: proj:<project-name> (<new or existing>)
- Epic: <epic-name> (<link>)
- Documents: PRD, Technical Design, ADR-001 (all linked to epic)

Next steps: flesh out TBD sections, create stories from the PRD requirements, begin implementation.

Important Principles

Don't fabricate content. If the conversation didn't cover security considerations, don't invent security requirements. Mark it TBD. The templates are a structure to fill, not a form to complete with placeholder text.

Respect what exists. If there's already a docs/PRD.md, read it and enhance/restructure it rather than overwriting. Ask the user if you're unsure.

The conversation is the source of truth. Templates provide structure. The conversation (and any existing docs) provide content. The skill's job is to map one onto the other.

Idempotency matters. The user might run this skill twice, or run it after manually creating some Shortcut artifacts. Always check before creating.