Project Init

Project Init Skill

Purpose

Initialize a new project with the SynthesisFlow directory structure and configuration files. This skill sets up the foundational folders needed for the spec-driven development workflow, creating a standard structure for specifications, change proposals, and documentation.

When to Use

Use this skill in the following situations:

• Starting a completely new project that will use SynthesisFlow
• Adding SynthesisFlow methodology to an existing project with no existing documentation
• Setting up a consistent structure for spec-driven development
• Ensuring project follows SynthesisFlow conventions from the beginning

Important: If the project already has documentation in a docs/ directory, use the project-migrate skill instead. It will properly catalog, categorize, and migrate existing documentation into the SynthesisFlow structure while preserving git history and updating links.

Prerequisites

• Write permissions to the target directory
• Git repository already initialized (recommended but not required)

Workflow

Step 1: Assess the Current Project State

Before initializing, determine:

• Is this a brand new project or an existing codebase?
• Does a docs/ directory already exist?
• If docs/ exists, does it contain markdown files?
• Where should the SynthesisFlow structure be created?

Decision Tree:

• No docs/ directory: Proceed with project-init (this skill)
• Empty docs/ directory: Proceed with project-init (this skill)
• docs/ with existing markdown files: Use project-migrate skill instead

The init-project.sh script will automatically detect existing documentation and suggest using project-migrate if appropriate.

Step 2: Run the Initialization Script

Execute the helper script to create the directory structure:

For current directory:

bash scripts/init-project.sh

For a specific directory:

bash scripts/init-project.sh -d /path/to/project

The script will create:

• docs/specs/ - Source-of-truth for approved specifications
• docs/changes/ - Staging area for proposed changes (Spec PRs)

Step 3: Verify Structure Creation

Check that the directories were created successfully:

ls -la docs/

Expected output:

docs/
├── specs/
└── changes/

Step 4: Initialize Supporting Files (Manual)

After the directory structure is created, consider adding these files:

Create RETROSPECTIVE.md (in project root):

cat > RETROSPECTIVE.md << 'EOF'
# Development Retrospective

This file captures learnings from completed tasks to inform and improve future development work.

## Active Improvements
EOF

Create AGENTS.md (using agent-integrator skill):

# Use the agent-integrator skill to create AGENTS.md
bash skills/agent-integrator/scripts/update-agents-file.sh

Step 5: Next Steps

After initialization, guide the user on getting started:

1. Create first specification: Use the spec-authoring skill to propose the first feature
2. Set up GitHub integration: Create GitHub repository if not exists, set up project board
3. Document the system: Add initial specs to docs/specs/ directory
4. Initialize git tracking: Ensure new directories are committed to version control

Error Handling

Directory Already Exists

Symptom: Script reports that directories already exist or initialization appears to do nothing

Solution:

• Check if docs/specs/ and docs/changes/ already exist
• If they exist, the project is already initialized
• No action needed - the script is idempotent

Permission Denied

Symptom: "Permission denied" when creating directories

Solution:

• Verify write permissions to the target directory
• Check if parent directory exists
• Try with appropriate permissions: sudo if necessary (rare)

Wrong Directory Initialized

Symptom: Directories created in unexpected location

Solution:

• Remove incorrect directories: rm -rf docs/
• Re-run with explicit path: bash scripts/init-project.sh -d /correct/path
• Always verify current working directory before running

Directory Structure Explained

docs/specs/

Purpose: Source-of-truth for all approved specifications

Contents:

• Approved specification files
• Design documents
• Architecture decisions
• System requirements

Example structure:

docs/specs/
├── 001-initial-system.md
├── 002-authentication.md
└── feature-name/
    ├── spec.md
    └── design.md

docs/changes/

Purpose: Staging area for proposed changes before approval

Contents:

• Change proposals in review
• Spec deltas for new features
• Task breakdowns
• Planning documents

Example structure:

docs/changes/
├── my-feature/
│   ├── proposal.md
│   ├── spec-delta.md
│   └── tasks.md
└── another-feature/
    └── proposal.md

Workflow: Changes start in docs/changes/, get approved via Spec PR, then move to docs/specs/

project-init vs project-migrate

Understanding when to use each skill:

Use project-init when:

• Starting a brand new project from scratch
• Project has no existing documentation
• docs/ directory is empty or doesn't exist
• You just need the basic SynthesisFlow directory structure

Use project-migrate when:

• Project has existing documentation in docs/ or other locations
• You want to migrate legacy docs into SynthesisFlow structure
• You need to preserve git history during migration
• Documentation has relative links that need updating
• You want doc-indexer compliant frontmatter added automatically

Smooth Handoff

The init-project.sh script automatically detects existing documentation and will:

1. Count markdown files in docs/ (excluding docs/specs/ and docs/changes/)
2. If found, display a recommendation to use project-migrate
3. Show the benefits of using project-migrate over basic initialization
4. Give you the option to continue with project-init or cancel

This ensures you always use the right skill for your situation.

Notes

• The script is idempotent - safe to run multiple times
• Existing directories won't be overwritten or deleted
• The script only creates directories, no files are created automatically
• Consider adding .gitkeep files to track empty directories in git
• This is just the directory scaffold - content comes from using other skills
• The structure is intentionally minimal - projects add what they need
• Detection logic: The script checks for markdown files in docs/, excluding those already in specs/ or changes/ subdirectories