New Project Creation

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

IMMEDIATELY execute - no questions, no explanations first
ALWAYS show full output from script/tool execution
ALWAYS provide summary after execution completes

DO NOT:

Say "I don't need to take action" - you ALWAYS execute when invoked
Ask for confirmation unless requires_confirmation: true in frontmatter
Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

Usage

/new-project <name>

Create new project: $ARGUMENTS

Arguments

$ARGUMENTS - Project Description (optional)

Specify project to create:

Project idea: "Build an API for managing team projects"
With details: "Create e-commerce platform with React frontend and Node.js backend"
No arguments: Starts interactive discovery interview

Flags

Flag	Description
`--guided`	Post-onboarding mode with extra guidance, explanations, and hand-holding
`--quick`	Skip discovery, use smart defaults based on project description
`--from-research <path>`	Skip discovery interview; use pre-populated research artifacts from `/research-pipeline` output directory. Expects: executive-summary.md, sdd.md, tdd.md, c4-architecture.md, coditect-impact.md, adrs/, research-context.json
`--venture`	Place project under `submodules/ventures/` as a venture submodule (vs generic category). Implies `--from-research` flow.
`--tracks`	Generate TRACK-{X}-*.md files + MASTER-TRACK-INDEX.md instead of TASKLIST.md. Derives tracks from SDD/TDD/ADR content.
`--register`	Auto-register in projects.db after creation
`--classify`	Auto-run `/classify` on all generated files after creation
`--dry-run`	Preview what will be created without making changes

Default Behavior

If no arguments:

Launches interactive discovery interview
Gathers comprehensive requirements
Creates project brief with risk assessment
Sets up complete production-ready project

Guided Mode (`--guided`)

For users who just completed onboarding and need extra support.

/new-project --guided "My first API project"

What's Different in Guided Mode

Standard Mode	Guided Mode
Assumes familiarity	Explains each step
Technical language	Friendly, accessible language
Minimal prompts	"Why this matters" context
5 phases, detailed	Same phases, with celebrations
Proceeds quickly	Confirms understanding

Guided Mode Flow

Phase 0: Welcome & Context Setting

Welcome to your first real CODITECT project!

You've completed onboarding, so you know the basics. Now let's build
something real together. I'll guide you through each step and explain
why it matters.

Your project idea: "[user's description]"

Let's make this happen! First, I need to understand what you're
building a bit better...

Phase 1: Simplified Discovery

Let's figure out what you're building. I'll ask a few questions:

1. Who is this for? (yourself, a client, your team, the public)
2. What's the ONE main thing it needs to do?
3. Do you have a deadline or is this exploratory?
4. Any technologies you definitely want to use? (or should I suggest?)

[After each answer, provide encouragement and context]

"Great choice! Building for yourself first means you can iterate
quickly without external pressure. That's how many successful
projects start!"

Phase 2: Project Creation with Explanations

Now I'm creating your project structure. Here's what's happening:

Creating: recipe-api/
  ├── docs/original-research/  ← Your research and notes go here
  ├── docs/architecture/       ← Technical decisions we'll make together
  ├── docs/project-management/ ← Your PROJECT-PLAN and TASKLIST
  ├── src/                     ← Your code will live here
  └── tests/                   ← Tests (yes, from day one!)

Why this structure? It separates concerns so you always know where
things belong. No more "where did I put that file?"

Phase 3: Planning with Guidance

Let's create your project plan. This is like a roadmap - you can
always adjust it, but having one helps you stay focused.

I'm generating:
- PROJECT-PLAN.md - The "what" and "why" of your project
- TASKLIST.md - Specific tasks with checkboxes (satisfying to check off!)

[After generation]

Your first 3 tasks are:
1. [ ] Set up development environment
2. [ ] Create basic project skeleton
3. [ ] Implement [core feature]

Pro tip: Start with task 1 today. Small wins build momentum!

Phase 4: Next Steps with Agent Recommendations

Your project is ready! Here's what to do next:

IMMEDIATE (Today):
  cd recipe-api
  cr "set up my development environment"

TOMORROW:
  Start on your first feature. Try:
  Task(
    subagent_type="general-purpose",
    prompt="Use backend-architect subagent to design the database
    schema for [your project's core feature]"
  )

ONGOING SUPPORT:
  I've activated the first-project-companion to help you along.
  It will check in and offer guidance as you work.

  To ask for help anytime:
  cr "I'm stuck on [problem]"

You've got this! 🎉

Guided Mode Detection

Guided mode auto-activates when:

User explicitly uses --guided flag
.coditect/onboarding-progress.json exists and completed_at < 7 days ago
User has no other projects in the system (first project)

Companion Activation

At the end of guided mode, the first-project-companion agent is automatically activated:

{
  "companion_activated": true,
  "project_name": "recipe-api",
  "activated_at": "2025-12-11T10:00:00Z",
  "check_in_frequency": "session_start",
  "guidance_level": "high"
}

Saved to: .coditect/companion-config.json

New Project Creation Workflow

This command orchestrates a complete new project creation workflow that guides users from initial idea through discovery, planning, and structure creation to have a production-ready project ready for development. The workflow is designed for CODITECT internal teams, enterprise customers, and end-users, with different guidance styles adapted to each audience.

The workflow progresses through five integrated phases with specialized agents handling each responsibility:

Project Discovery - Interactive interview to gather requirements and create project brief
Submodule Creation - Automated git repository setup with CODITECT distributed intelligence
Project Planning - Comprehensive specification generation (PROJECT-PLAN.md, TASKLIST.md)
Structure Optimization - Production-ready directory structure and starter templates
Quality Assurance - Verification that everything is in place and ready for development

Steps to follow:

Step 1: Initiate Project Discovery

If --from-research <path> is provided: Skip the interactive discovery interview entirely. Instead, read the research pipeline output directory and construct a project brief from the pre-populated artifacts:

if args.from_research:
    research_dir = args.from_research
    project_brief = {
        "source": "research-pipeline",
        "topic": read_json(f"{research_dir}/research-context.json").get("topic"),
        "executive_summary": read(f"{research_dir}/executive-summary.md"),
        "sdd": read(f"{research_dir}/sdd.md"),
        "tdd": read(f"{research_dir}/tdd.md"),
        "c4": read(f"{research_dir}/c4-architecture.md"),
        "impact": read(f"{research_dir}/coditect-impact.md"),
        "adrs": read_dir(f"{research_dir}/adrs/"),
        "glossary": read(f"{research_dir}/glossary.md"),
        "quick_start": read(f"{research_dir}/1-2-3-detailed-quick-start.md"),
    }
    # Validate all required files exist
    missing = [k for k, v in project_brief.items() if v is None]
    if missing:
        warn(f"Missing research artifacts: {missing}. Running partial genesis.")
    # Proceed directly to Step 2 (Submodule Creation) with pre-populated brief

Otherwise (default): Launch the interactive discovery phase with the project-discovery-specialist agent to gather comprehensive project requirements.

Action: Invoke the discovery specialist agent to conduct an interactive discovery interview.

Task(
    subagent_type="orchestrator",
    prompt="""Use project-discovery-specialist subagent to conduct a comprehensive interactive discovery interview for a new project.

The discovery process should:
1. Ask adaptive questions based on initial project description
2. Gather functional and non-functional requirements
3. Assess team, timeline, and resource constraints
4. Identify risks and mitigation strategies
5. Document business case and success criteria
6. Generate a complete project brief in JSON format

Output the project brief and be prepared to pass it to the planning phase."""
)

Success Criteria:

Project brief created with all required sections
User confirms understanding of scope and requirements
Risk assessment complete with mitigation strategies
Business case documented with success metrics
Tech stack recommendations provided
No major ambiguities or conflicting requirements remain

Common Issues & Solutions:

User uncertain about scope → Ask clarifying questions until scope is clear
Conflicting requirements → Surface conflicts and guide user to prioritization
Unrealistic timeline → Discuss scope/team tradeoffs
Risk level too high → Explore risk mitigation strategies

Step 2: Create Submodule Repository

Create the git repository and submodule infrastructure using the submodule-orchestrator agent.

Venture Mode (--venture): When --venture is set, the project is placed under submodules/ventures/ with a simplified naming convention ({project-name} instead of coditect-{category}-{name}). This is for business ventures, market explorations, and joint ventures that originate from the research pipeline.

if args.venture:
    # Venture naming: project-name (not coditect-category-name)
    project_name = slugify(topic)  # e.g., "chamber-of-commerce-canada"
    submodule_path = f"submodules/ventures/{project_name}"
    github_repo = f"coditect-ai/{project_name}"
else:
    # Standard naming: coditect-{category}-{name}
    category = determine_category(project_brief)
    project_name = f"coditect-{category}-{slugify(topic)}"
    submodule_path = f"submodules/{category}/{project_name}"
    github_repo = f"coditect-ai/{project_name}"

Action: Invoke the submodule orchestrator to set up git repository structure.

Task(
    subagent_type="orchestrator",
    prompt="""Use submodule-orchestrator subagent to create a new CODITECT submodule for the project.

The submodule creation should:
1. Determine appropriate category (cloud, dev, ops, etc.) based on project type
   - If --venture: use submodules/ventures/ path
2. Create git repository with proper naming convention
   - If --venture: {project-name} (no coditect- prefix)
   - Otherwise: coditect-{category}-{name}
3. Create all required directories and symlinks (.coditect, .claude)
4. Initialize git with first commit
5. Create GitHub repository
6. Register as submodule with parent repository
7. Verify all components are in place

Use the project brief from Step 1 to guide decisions about naming and structure."""
)

Success Criteria:

Git repository created with correct naming convention
Symlink chains established (.coditect → ../../../.coditect, .claude → .coditect)
GitHub repository created and configured
Submodule registered with parent repository
Initial commit created and pushed
All verification checks pass

Important Notes:

Use REPO-NAMING-CONVENTION.md to determine correct category
Repository name must follow coditect-{category}-{name} format
Symlinks are critical for distributed intelligence architecture
Verify symlink accessibility after creation

Step 3: Generate Project Plan

Create comprehensive project specification using the software-design-document-specialist agent.

TRACK Mode (--tracks): When --tracks is set (implied by --venture), generate CODITECT TRACK files instead of a single TASKLIST.md. TRACK files follow the ADR-054 nomenclature standard with Track.Section.Task[.Subtask] IDs.

if args.tracks or args.venture:
    # Generate TRACK files from research artifacts
    # Derive tracks based on content in SDD, TDD, ADRs, exec summary
    tracks_to_generate = derive_tracks(project_brief)
    # Standard venture tracks:
    # R - Research & Analysis (auto-complete: all research tasks marked [x])
    # V - Validation & Partnerships (from exec summary recommendations)
    # D - Development & Engineering (from SDD sections + TDD APIs)
    # G - Go-to-Market & Sales (from GTM/marketing strategy)
    # O - Operations & Compliance (from compliance ADRs, regulatory sections)
    for track in tracks_to_generate:
        Task(subagent_type="orchestrator", prompt=f"""
        Generate TRACK-{track.letter}-{track.name}.md with:
        - YAML frontmatter (type, track, status, governance)
        - Status Summary with progress
        - Sections with checkbox tasks derived from {track.source_artifacts}
        - Task IDs in Track.Section.Task format
        Output: {project_path}/internal/project/plans/tracks/
        """)
    # Generate MASTER-TRACK-INDEX.md
    Task(subagent_type="orchestrator", prompt="""
    Generate MASTER-TRACK-INDEX.md summarizing all tracks,
    task counts, phase timeline, and critical path.
    """)
else:
    # Standard mode: generate TASKLIST.md
    pass  # Existing behavior

Action: Invoke the design specialist to create detailed project plan.

Task(
    subagent_type="orchestrator",
    prompt="""Use software-design-document-specialist subagent to create a comprehensive PROJECT-PLAN.md for the project.

The project plan should include:
1. Executive summary of project scope and goals
2. System architecture and design (C4 if applicable)
3. Detailed requirements breakdown (functional and non-functional)
4. Technology stack rationale
5. Implementation roadmap with phases
6. Risk assessment and mitigation strategies
7. Success metrics and quality gates
8. Dependencies and integration points
9. Team structure and roles
10. Budget and resource requirements

If --tracks or --venture:
  Generate TRACK-{X}-*.md files + MASTER-TRACK-INDEX.md
  (CODITECT standard track files with ADR-054 nomenclature)
Otherwise:
  Generate TASKLIST.md with checkbox-based tracking

Use the project brief from Step 1 as comprehensive input."""
)

Success Criteria:

PROJECT-PLAN.md complete with all sections filled in
TASKLIST.md created with 50+ tasks broken down by phase
Architecture diagrams included (if applicable)
Implementation roadmap with realistic timeline
Risk assessment documented with mitigation plans
All checkboxes ready for progress tracking
Documentation is clear enough for development team to start immediately

Important Notes:

Plan must be comprehensive enough to guide development without further discovery
Include clear acceptance criteria for each phase
Document all assumptions and constraints
Provide architecture diagrams when applicable
Break down into phases with clear deliverables

Step 4: Optimize Project Structure

Create production-ready directory structure using the project-structure-optimizer agent.

Action: Invoke the structure optimizer to generate project directory hierarchy.

Task(
    subagent_type="orchestrator",
    prompt="""Use project-structure-optimizer subagent to create a production-ready project structure.

The structure optimization should:
1. Analyze project type and tech stack from project brief
2. Create optimal directory hierarchy following CODITECT standards
3. Generate starter code templates for primary components
4. Create example implementations showing best practices
5. Generate configuration templates (dev, staging, prod)
6. Create GitHub Actions CI/CD templates
7. Generate Dockerfile and docker-compose.yml for local development
8. Create comprehensive documentation (README, CONTRIBUTING, DEVELOPMENT, ARCHITECTURE)
9. Set up testing structure with example tests
10. Create Makefile or equivalent for common tasks

The structure should be completely production-ready so developers can:
- Clone the repository
- Install dependencies
- Run the application
- Start development with confidence

Use the project brief and plan from previous steps as input."""
)

Success Criteria:

Directory structure matches CODITECT production standards
All starter code is production-quality
Configuration templates provided for all environments
CI/CD workflows set up and ready to use
Documentation is comprehensive and clear
Developers can run make dev or equivalent and start coding
No manual setup or file reorganization needed
Testing structure in place with examples

Important Notes:

Structure should support growth from MVP to enterprise scale
Include security best practices in templates
Provide performance optimization patterns
Support team collaboration patterns
Include monitoring and observability hooks from the start

Step 5: Quality Assurance Verification

Run comprehensive verification to ensure all phases completed successfully.

Action: Execute verification checks to validate the complete setup.

Task(
    subagent_type="orchestrator",
    prompt="""Use submodule-orchestrator subagent to run comprehensive QA verification for the new project.

The verification should check:
1. Git repository exists and is properly configured
2. Symlinks are properly established and accessible
3. PROJECT-PLAN.md is complete with all sections
4. TASKLIST.md has all tasks with checkboxes
5. Directory structure matches expected patterns
6. All starter files are in place and syntactically correct
7. Configuration files (env templates, docker, CI/CD) are complete
8. Documentation is complete and accurate
9. No broken references or missing files
10. Project is ready for team onboarding

Generate a QA report showing:
- All checks passed (green ✓)
- Any issues found (red ✗)
- Remediation steps for any failures
- Next steps for beginning development
- Team onboarding checklist"""
)

Success Criteria:

All verification checks pass (100% green)
QA report generated and reviewed
Any issues immediately remediated
Project is production-ready
Team can begin development immediately
Clear next steps documented

Important Notes:

Don't skip verification even if previous steps appeared successful
Fix any issues immediately before declaring complete
Generate team onboarding checklist
Provide clear documentation on how to get started

Step 6: Post-Creation Automation (Optional)

When --register, --classify, or --venture flags are set, execute post-creation steps:

# Step 6.1: Register in projects.db (--register or --venture)
if args.register or args.venture:
    Bash(f"""
    cd {CODITECT_CORE} && source .venv/bin/activate
    python3 scripts/project_registration.py register \\
        --name "{project_name}" \\
        --path "{submodule_path}" \\
        --github "coditect-ai/{repo_name}" \\
        --type submodule
    """)

# Step 6.2: Frontmatter classification (--classify or --venture)
if args.classify or args.venture:
    invoke("/classify", f"{submodule_path}/")
    # Commit classification changes
    Bash(f"""
    cd {submodule_path}
    git add -A
    git commit -m "chore: Standardize CODITECT frontmatter"
    """)

# Step 6.3: Session log inception (--venture)
if args.venture:
    invoke("/session-log",
        f'--new-session "{topic} — Project Genesis" --project {project_id}')

Success Criteria:

Project appears in projects.db with valid UUID
All files have CODITECT frontmatter with moe_confidence
Session log created at SSOT location

Important notes:

Adaptive to audience: Tailor guidance, terminology, and process based on whether this is for CODITECT internal teams (full control), enterprise customers (guided + compliance), or end-users (simplified + smart defaults)
Seamless integration: Each phase builds on the previous one, with artifacts from each phase feeding into the next. The orchestrator agent coordinates all five agents to ensure smooth handoff.
Complete by end: After all five phases complete successfully, the project is production-ready. Developers should be able to clone, setup, and start coding immediately.
Risk-aware: Identify risks early (during discovery) so they can be addressed during planning. Escalate high-risk projects to human review before proceeding.
Documentation complete: All documentation generated during the workflow (PROJECT-PLAN.md, TASKLIST.md, architecture docs, API docs, deployment guides) is ready for the team.
No manual work required: The workflow is fully automated. No manual file creation, folder organization, or configuration needed after the workflow completes.
Verification mandatory: Always run QA verification before considering the project complete. Don't assume previous steps were successful.
Extensible design: The modular architecture allows for future enhancements (add templates, customize structures, add compliance checks) without disrupting the core workflow.
Team collaboration ready: Generated structure and documentation support team collaboration patterns. Git workflow, code review processes, and CI/CD are all pre-configured.
Monitoring from day one: All starter code includes observability hooks. Developers don't need to retrofit monitoring; it's built in from the beginning.

Action Policy

<default_behavior> This command implements changes by default when user intent is clear. Proceeds with:

Code generation/modification
File creation/updates
Configuration changes
Git operations (if applicable)

Provides concise progress updates during execution. </default_behavior>

After execution, verify: - Files created/modified as intended - Code compiles/tests pass (if applicable) - Git changes committed (if applicable) - Next recommended step provided

Success Output

When new-project completes:

✅ COMMAND COMPLETE: /new-project
Project: <project-name>
Category: <category> (or ventures/ if --venture)
Structure: Created
Plan: PROJECT-PLAN.md generated
Tasks: TRACK files generated (if --tracks/--venture) or TASKLIST.md
Registered: projects.db (if --register/--venture)
Classified: Frontmatter standardized (if --classify/--venture)
Session Log: Created (if --venture)
Status: Production-ready

Completion Checklist

Before marking complete:

Failure Indicators

This command has FAILED if:

❌ No project name
❌ Discovery incomplete
❌ Repository not created
❌ QA verification failed

When NOT to Use

Do NOT use when:

Adding to existing project
Simple file creation
Non-CODITECT project

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip discovery	Unclear requirements	Complete full discovery
Skip QA	Broken project	Always run verification
Manual structure	Inconsistent	Use automated setup

Principles

This command embodies:

#3 Complete Execution - Full project creation
#1 Self-Provisioning - Automated setup
#6 Clear, Understandable - Clear project structure

Full Standard: CODITECT-STANDARD-AUTOMATION.md

System Prompt​

Usage​

Arguments​

$ARGUMENTS - Project Description (optional)​

Flags​

Default Behavior​

Guided Mode (--guided)​

What's Different in Guided Mode​

Guided Mode Flow​

Guided Mode Detection​

Companion Activation​

New Project Creation Workflow

Steps to follow:​

Step 1: Initiate Project Discovery​

Step 2: Create Submodule Repository​

Step 3: Generate Project Plan​

Step 4: Optimize Project Structure​

Step 5: Quality Assurance Verification​

Step 6: Post-Creation Automation (Optional)​

Important notes:​

Action Policy​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​

System Prompt

Usage

Arguments

$ARGUMENTS - Project Description (optional)

Flags

Default Behavior

Guided Mode (`--guided`)

What's Different in Guided Mode

Guided Mode Flow

Guided Mode Detection

Companion Activation

Steps to follow:

Step 1: Initiate Project Discovery

Step 2: Create Submodule Repository

Step 3: Generate Project Plan

Step 4: Optimize Project Structure

Step 5: Quality Assurance Verification

Step 6: Post-Creation Automation (Optional)

Important notes:

Action Policy

Success Output

Completion Checklist

Failure Indicators

When NOT to Use

Anti-Patterns (Avoid)

Principles