kf-setup

name	kf-setup
description	Initialize project with Kiloforge artifacts (product definition, tech stack, workflow, style guides)
metadata	{"argument-hint":"[--resume]"}

Kiloforge Setup

Initialize or resume Kiloforge project setup. This command creates foundational project documentation through interactive Q&A, pre-populated from existing project documentation when available.

Use this skill when

• Working on kiloforge setup tasks or workflows
• Needing guidance, best practices, or checklists for kiloforge setup

Do not use this skill when

• The task is unrelated to kiloforge setup
• You need a different domain or tool outside this scope

Instructions

• Clarify goals, constraints, and required inputs.
• Apply relevant best practices and validate outcomes.
• Provide actionable steps and verification.
• If detailed examples are required, open resources/implementation-playbook.md.

Phase 0: Repository Check

Step 0a — Detect git repository

git rev-parse --git-dir 2>/dev/null

If this fails (not inside a git repo), present the clone options:

This directory is not a git repository. How would you like to set up?

1. Clone an existing repository
2. Initialize a new repo here (git init)

If the user chooses 1 (Clone):

Ask for the repo URL:

Enter the repository URL (e.g., [e-mail]:org/repo.git):

Then ask which clone mode:

How should the repo be cloned?

1. Standard clone — single working tree, simple workflow
   Best for: solo development, small teams, straightforward projects

2. Worktree clone — bare repo with worktrees for parallel agents
   Best for: multi-agent parallel development with kiloforge conductor

Standard clone:

git clone <url> .

If the directory is not empty, clone into a subdirectory:

git clone <url>
cd <repo-name>

Worktree clone:

Clone bare into a hidden .bare/ directory with a .git file pointer, matching the conductor's expected layout:

git clone --bare <url> .bare
echo "gitdir: ./.bare" > .git
git config core.bare false
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin

# Detach HEAD so worktrees can checkout the primary branch.
# A bare clone's HEAD points to the default branch, blocking worktree add.
PRIMARY_BRANCH=$(git symbolic-ref HEAD | sed 's|refs/heads/||')
git update-ref --no-deref HEAD $(git rev-parse HEAD)

# Create the primary worktree
git worktree add "${PRIMARY_BRANCH}" "${PRIMARY_BRANCH}"
cd "${PRIMARY_BRANCH}"

Inform the user:

Bare repo at:          {path}/.bare/
Primary worktree at:   {path}/{PRIMARY_BRANCH}/

Worktrees for architect and developer agents will be created automatically
by the conductor. You are now in the primary worktree.

Skip the primary branch question in Phase 1 — it was already determined from the bare repo HEAD. The conductor auto-detects the bare repo / worktree layout at runtime, so no clone mode needs to be stored.

If the user chooses 2 (New repo):

git init

Continue to Phase 1 as normal.

Step 0b — Scan existing project documentation

This step runs BEFORE any interactive questions. If we are in an existing git repo (brownfield project), scan for documentation and code that can pre-populate setup answers. This dramatically reduces the number of questions the user needs to answer.

Scan for documentation files:

# Find common documentation files
find . -maxdepth 3 -type f \( \
  -iname "README*" -o -iname "CONTRIBUTING*" -o -iname "ARCHITECTURE*" \
  -o -iname "DESIGN*" -o -iname "REQUIREMENTS*" -o -iname "PRD*" \
  -o -iname "SPEC*" -o -iname "TODO*" -o -iname "ROADMAP*" \
  -o -iname "CHANGELOG*" -o -iname "package.json" -o -iname "pyproject.toml" \
  -o -iname "Cargo.toml" -o -iname "go.mod" -o -iname "Makefile" \
  -o -iname "Dockerfile" -o -iname "docker-compose*" \
  -o -iname ".eslintrc*" -o -iname ".prettierrc*" -o -iname "tsconfig*" \
  -o -iname "requirements*.txt" -o -iname "setup.py" -o -iname "setup.cfg" \
\) 2>/dev/null | head -50

Read and analyze each found file (use the Read tool). Extract:

• Project name — from package.json name, go.mod module, Cargo.toml [package].name, pyproject.toml [project].name, or README title
• Description — from package.json description, README first paragraph, pyproject.toml [project].description
• Languages — from file extensions (.ts, .py, .go, .rs), config files (tsconfig.json, pyproject.toml, go.mod, Cargo.toml)
• Frameworks — from dependencies (package.json deps, requirements.txt, go.mod requires)
• Database — from dependencies (pg, mysql, mongo, sqlite, prisma, sqlalchemy, gorm)
• Infrastructure — from Dockerfile, docker-compose, serverless.yml, Procfile, vercel.json, netlify.toml
• Problem statement / goals — from README "About", "Overview", "Goals" sections; PRD files; SPEC files
• Target users — from README, PRD, or CONTRIBUTING docs
• Existing linting/formatting — from .eslintrc, .prettierrc, pyproject.toml [tool.*], .golangci.yml
• Test framework — from jest.config, pytest.ini, go test patterns, test directories
• Commit conventions — from CONTRIBUTING.md, .commitlintrc, or recent git log patterns

Store all discovered information in a _discovery dict for use during Q&A. This information will be presented to the user for confirmation rather than asking from scratch.

Phase 1: Pre-flight Checks

1. Determine primary branch:

   The primary branch is the trunk branch used for coordination. All kiloforge artifacts, track state, and merged work live here. Architect and developer agents read from and merge into this branch.

   Auto-detect the primary branch (try in order, use first match):

   # 1. Remote HEAD (most reliable — reflects repo default branch)
   git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'
   
   # 2. git config init.defaultBranch
   git config init.defaultBranch 2>/dev/null
   
   # 3. Check if common branch names exist locally
   git rev-parse --verify main 2>/dev/null && echo "main"
   git rev-parse --verify master 2>/dev/null && echo "master"
   

   Present the result for confirmation:

   The primary branch is the trunk used for coordination — all kiloforge
   artifacts, track state, and merged work live here.
   
   [If detected]: I detected "{detected_branch}" as your primary branch.
     1. Yes, use {detected_branch}
     2. Use a different branch (type name)
   
   [If not detected]: What is your primary branch?
     1. main
     2. master
     3. develop
     4. Type your own
   

   Store the answer in setup_state.json as "primary_branch": "<branch>".

   Then ask:

   Should I commit the setup artifacts to {primary_branch} when complete?
   
   1. Yes, commit to {primary_branch} (recommended)
   2. No, I'll commit manually
   

   Store as "auto_commit": true|false.

2. Verify Python 3:

   python3 --version 2>/dev/null
   

   If Python 3 is not available, ask the user:

   Kiloforge CLI tools require Python 3, which was not found on this system.
   
   May I install Python on this machine?
   
   1. Yes, install Python
   2. No, I'll install it myself
   

   If the user chooses 1, detect the platform and install:

   • macOS: brew install python3 (if brew available), otherwise suggest https://python.org
   • Linux (Debian/Ubuntu): sudo apt-get install -y python3 python3-pip python3-venv
   • Linux (Fedora/RHEL): sudo dnf install -y python3 python3-pip
   • Linux (Arch): sudo pacman -S --noconfirm python python-pip
   • Windows: winget install Python.Python.3 (if winget available)

   If no package manager is detected, suggest downloading from https://python.org.

   If the user chooses 2: HALT — Python 3 is required to continue.

3. Run the install script to scaffold the project and install CLI tools:

   python3 "$SKILL_DIR/../kf-bin/scripts/kf-install.py" \
     --project-dir "$(pwd)" \
     --primary-branch "{primary_branch from step 1}"
   

   This sets up global tools and per-project metadata in one call:

   • Global venv at ~/.kf/.venv with PyYAML
   • Global CLI tools at ~/.kf/bin/ with shebangs pointing to the venv
   • .agent/kf/.gitignore with __pycache__/ entries
   • Empty metadata files (config, product, tech-stack, workflow)
   • Version file at ~/.kf/VERSION

   Existing metadata files are never overwritten — safe to re-run.

   If $SKILL_DIR is not available, ask for the kiloforge-skills repo path and use --skills-dir.

4. Check if .agent/kf/setup_state.json has status "complete" or "in_progress":

   • If "complete" and no --resume: Ask user whether to reconfigure or keep existing setup
   • If "in_progress" or "scaffolded": Offer to resume from last section

5. Detect project type by checking for existing indicators:

   • Greenfield (new project): No .git history, no package.json, no requirements.txt, no go.mod, no src/ directory
   • Brownfield (existing project): Any of the above exist

Phase 2: Interactive Q&A Protocol

CRITICAL RULES:

• Ask ONE question per turn
• Wait for user response before proceeding
• If a value was discovered in Phase 0 Step 0b, present it for confirmation instead of asking from scratch: "I found: {value}. Is this correct? (y/n/edit)"
• Offer 2-3 suggested answers plus "Type your own" option for undiscovered values
• Maximum 5 questions per section
• Update setup_state.json after each successful step
• Validate file writes succeeded before continuing

Section 1: Product Definition (max 5 questions)

Q1: Project Name

[If discovered]: I found your project name is "{name}" (from {source}). Is this correct?
  1. Yes
  2. Change to something else

[If not discovered]:
What is your project name?

Suggested:
1. [Infer from directory name]
2. [Infer from package.json/go.mod if brownfield]
3. Type your own

Q2: Project Description

[If discovered]: From your README, the project description appears to be:
  "{description}"
  Is this correct?
  1. Yes
  2. Edit

[If not discovered]:
Describe your project in one sentence.

Suggested:
1. A web application that [does X]
2. A CLI tool for [doing Y]
3. Type your own

Q3: Problem Statement

[If discovered from README/PRD]: I found this problem statement:
  "{problem}"
  Is this correct?
  1. Yes
  2. Edit

[If not discovered]:
What problem does this project solve?

Suggested:
1. Users struggle to [pain point]
2. There's no good way to [need]
3. Type your own

Q4: Target Users

[If discovered]: Target users appear to be: {users}. Correct?
  1. Yes
  2. Edit

[If not discovered]:
Who are the primary users?

Suggested:
1. Developers building [X]
2. End users who need [Y]
3. Internal teams managing [Z]
4. Type your own

Q5: Key Goals (optional)

[If discovered from README/roadmap]: I found these goals:
  {goals}
  Are these correct? (y/n/edit)

[If not discovered]:
What are 2-3 key goals for this project? (Press enter to skip)

Section 2: Product Guidelines (max 3 questions)

Q1: Voice and Tone

What voice/tone should documentation and UI text use?

Suggested:
1. Professional and technical
2. Friendly and approachable
3. Concise and direct
4. Type your own

Q2: Design Principles

What design principles guide this project?

Suggested:
1. Simplicity over features
2. Performance first
3. Developer experience focused
4. User safety and reliability
5. Type your own (comma-separated)

Section 3: Tech Stack (max 5 questions)

For brownfield projects, present the discovered tech stack for confirmation before asking additional questions.

[If brownfield with discoveries]:
I analyzed your codebase and found:

  Languages:      {languages}
  Frontend:       {frontend or "none detected"}
  Backend:        {backend or "none detected"}
  Database:       {database or "none detected"}
  Infrastructure: {infra or "none detected"}

Is this correct? What would you like to change?
  1. Looks good, continue
  2. Let me make corrections (specify what to change)

Only ask individual questions for values NOT discovered. Skip questions where discovery found clear answers and the user confirmed them.

Q1: Primary Language(s)

[If discovered]: I detected: {languages}. Correct?
  1. Yes
  2. Edit

[If not discovered]:
What primary language(s) does this project use?

Suggested:
1. TypeScript
2. Python
3. Go
4. Rust
5. Type your own (comma-separated)

Q2: Frontend Framework (if applicable)

[If discovered]: I detected {framework} from {source}. Correct?

[If not discovered]:
What frontend framework (if any)?

Suggested:
1. React
2. Vue
3. Next.js
4. None / CLI only
5. Type your own

Q3: Backend Framework (if applicable)

[If discovered]: I detected {framework} from {source}. Correct?

[If not discovered]:
What backend framework (if any)?

Suggested:
1. Express / Fastify
2. Django / FastAPI
3. Go standard library
4. None / Frontend only
5. Type your own

Q4: Database (if applicable)

[If discovered]: I detected {database} from {source}. Correct?

[If not discovered]:
What database (if any)?

Suggested:
1. PostgreSQL
2. MongoDB
3. SQLite
4. None / Stateless
5. Type your own

Q5: Infrastructure

[If discovered]: I detected {infra} from {source}. Correct?

[If not discovered]:
Where will this be deployed?

Suggested:
1. AWS (Lambda, ECS, etc.)
2. Vercel / Netlify
3. Self-hosted / Docker
4. Not decided yet
5. Type your own

Section 4: Workflow Preferences (max 2 questions)

TDD is strict by default. Do not ask about TDD strictness — it is always set to strict. This will be confirmed at the end during the review step.

Q1: Commit Strategy

[If discovered from CONTRIBUTING.md or recent git log]:
I detected you use {convention} commits. Keep this?
  1. Yes
  2. Change

[If not discovered]:
What commit strategy should be followed?

Suggested:
1. Conventional Commits (feat:, fix:, etc.)
2. Descriptive messages, no format required
3. Squash commits per task

Defaults (not asked):

The following are set automatically and do not require user input:

• TDD: Strict — tests required before implementation
• Code review: Optional / self-review OK
• Verification checkpoints: Track completion only — manual verification is required only when an entire track is complete. Individual phases and tasks do not require manual sign-off.

Section 5: Code Style Guides (max 2 questions)

Q1: Languages to Include

Which language style guides should be generated?

[Based on detected languages, pre-select]

Options:
1. TypeScript/JavaScript
2. Python
3. Go
4. Rust
5. All detected languages
6. Skip style guides

Q2: Existing Conventions

[For brownfield]: I found {configs}. Should I incorporate these?

Suggested:
1. Yes, use existing configs
2. No, generate fresh guides
3. Skip this step

Phase 3: Confirmation

Before generating artifacts, present a summary of all collected information for the user to review and confirm:

Here's what I've gathered for your project:

  Project:       {name}
  Description:   {description}
  Problem:       {problem}
  Users:         {users}
  Goals:         {goals}

  Tech Stack:
    Languages:      {languages}
    Frontend:       {frontend}
    Backend:        {backend}
    Database:       {database}
    Infrastructure: {infrastructure}

  Workflow:
    TDD:          Strict (tests required before implementation)
    Commits:      {commit_strategy}

  Style Guides:  {languages to generate}

Does this look correct? Any changes?
  1. Looks good, generate artifacts
  2. I'd like to change something (specify)

This is where the user can override TDD strictness or any other value if they specifically want to. Only change if the user explicitly requests it.

Phase 3b: Product Specification Proposal

After the user confirms the project summary, propose an initial product specification. This is derived from everything gathered so far — product definition, goals, tech stack, and any documentation discovered in Phase 0.

Generate proposed spec items using hierarchical dot notation. There are two types of spec items:

• Product items (WHAT) — User-facing capabilities. IDs: product.{domain}.{capability}
• Technical items (HOW) — Implementation constraints/decisions. IDs: tech.{domain}.{constraint}

Group by domain area. For example, a web app with auth and an API might produce:

Based on your project definition, here's a proposed product specification:

  PRODUCT ITEMS (WHAT users can do):
  product.auth.login           [high]    User login with email/password
  product.auth.registration    [high]    New user registration flow
  product.auth.password-reset  [medium]  Password reset via email
  product.api.users            [high]    User CRUD endpoints
  product.data.export          [low]     Export user data as CSV/JSON
  product.ui.dashboard         [high]    Main dashboard view
  product.ui.settings          [medium]  User settings page

  TECHNICAL ITEMS (HOW it should be built):
  tech.api.cursor-pagination   [high]    All list endpoints use cursor pagination
  tech.api.rate-limiting       [medium]  Per-user API rate limiting
  tech.auth.jwt-rs256          [high]    JWT tokens with RS256 signing

Product items define WHAT the product should do. Technical items define
HOW it should be built. Tracks link to these via spec_refs when created
by architects.

What would you like to do?
  1. Accept this specification
  2. Edit (add, remove, or modify items)
  3. Skip — start with an empty spec (architects will build it incrementally)

If the user chooses 1 (Accept):

• Create .agent/kf/spec.yaml with all proposed items (status: active, added_by: _init)
• Create a spec operation file at .agent/kf/spec/{timestamp}-{hash}-init.yaml recording the initial operations
• Use ~/.kf/bin/kf-track.py spec op add <item-id> --title "..." --type product|technical to draft each item, then ~/.kf/bin/kf-track.py spec op finalize --description "Initial product spec" to finalize

If the user chooses 2 (Edit):

• Let the user add/remove/modify items interactively
• Use the same CLI commands to draft and finalize the operation file

If the user chooses 3 (Skip):

• Create an empty .agent/kf/spec.yaml (version 1, no items)
• Do NOT create any operation files
• Inform the user: "Architects will add spec items via kf-track spec op add as they research and create tracks."

Guidelines for proposing spec items:

• Derive from goals, description, and problem statement — not from implementation details
• Use hierarchical IDs with type prefix:
  • Product items: product.{domain}.{capability} (e.g., product.auth.oauth2, product.api.users)
  • Technical items: tech.{domain}.{constraint} (e.g., tech.api.cursor-pagination, tech.auth.jwt-rs256)
• Assign priority: high (core to the product), medium (important), low (nice-to-have)
• Keep descriptions concise (one sentence)
• For greenfield projects with minimal info, propose fewer items (3-5)
• For brownfield projects with existing code, analyze the codebase structure to identify existing capabilities and propose spec items that cover both what exists and what's planned
• Product items describe WHAT users can do — technical items describe HOW it should be built
• Both types are independently valuable: product items guide feature planning, technical items enforce architectural consistency

Phase 4: Artifact Generation

After completing Q&A, populate the metadata files that were scaffolded by kf-install.py in the pre-flight step. The scaffolding already created empty templates — this step fills them with the user's answers.

1. .agent/kf/config.yaml

Update with the project name from Q&A:

project_name: "{project name}"
primary_branch: "{primary_branch from pre-flight}"

2. .agent/kf/product.yaml

Populate with Q&A answers: project name, description, problem statement, target users, key goals.

3. .agent/kf/product-guidelines.yaml

Populate with Q&A answers: voice/tone, design principles.

4. .agent/kf/tech-stack.yaml

Populate with Q&A answers: languages, frameworks, database, infrastructure, dependencies.

5. .agent/kf/workflow.yaml

Populate with: TDD = strict, commit strategy from Q&A. Defaults: code review = optional, verification = track completion only.

6. .agent/kf/spec.yaml and .agent/kf/spec/

Created during Phase 3b. If the user accepted or edited a specification:

• spec.yaml contains the materialized snapshot with all initial items
• spec/{timestamp}-{hash}-init.yaml contains the operation file recording the initial added operations

If the user skipped, spec.yaml is created empty:

version: 1
snapshot_date: "{today}"
snapshot_after_tracks: []
snapshot_after_ops: []
items: {}

The spec/ directory is created regardless (architects will write operation files there).

7. .agent/kf/code_styleguides/

Generate style guide files based on the languages selected in Section 5. For each selected language, create a markdown file (e.g., typescript.md, python.md, go.md) in .agent/kf/code_styleguides/ containing:

• Naming conventions (files, variables, functions, classes, constants)
• Code organization patterns
• Import ordering
• Error handling conventions
• Testing conventions
• Formatting rules (incorporate existing linting/formatting configs if user chose to in Q2)

If the user chose "Skip style guides" in Section 5, skip this step entirely.

State Management

After each successful file creation:

1. Update setup_state.json:
   • Add filename to files_created array
   • Update last_updated timestamp
   • If section complete, add to completed_sections
2. Verify file exists with Read tool

Completion

When all files are created:

1. Set setup_state.json status to "complete"

2. If auto_commit is true:

   • Verify the current branch is {primary_branch}. If not, warn and ask to switch.
   • Stage all .agent/kf/ files: git add .agent/kf/
   • Commit: git commit -m "chore(kf): initialize kiloforge project artifacts"
   • Inform the user the commit was made to {primary_branch}

3. Display summary:

   Kiloforge setup complete!
   
   Project:  {project_name}
   Branch:   {primary_branch}
   Artifacts: .agent/kf/
   
   [If committed: "Artifacts committed to {primary_branch}."]
   [If not committed: "Remember to commit .agent/kf/ to {primary_branch} — kf-* skills require these artifacts on the primary branch."]
   
   Next steps:
   1. Review generated files and customize as needed
   2. Run /kf-architect to design and create your first track
   3. To update CLI tools later, run /kf-update
   

Resume Handling

If --resume argument or resuming from state:

1. Load setup_state.json
2. Skip completed sections
3. Resume from current_section and current_question
4. Verify previously created files still exist
5. If files missing, offer to regenerate

Error Handling

• If file write fails: Halt and report error, do not update state
• If user cancels: Save current state for future resume
• If state file corrupted: Offer to start fresh or attempt recovery