Project Init Skill

Purpose

Initialize a new project with the AgenticDev 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 AgenticDev
• •Adding AgenticDev methodology to an existing project with no existing documentation
• •Setting up a consistent structure for spec-driven development
• •Ensuring project follows AgenticDev 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 AgenticDev 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 AgenticDev 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 AgenticDev directory structure

Use project-migrate when:

• •Project has existing documentation in docs/ or other locations
• •You want to migrate legacy docs into AgenticDev 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