Setup ASDLC

Overview

Initialize a repository for ASDLC adoption by creating AGENTS.md template, directory structure (specs/, .plans/), and basic configuration. This command prepares repositories to use ASDLC patterns while remaining optional—other commands work without running setup.

Definitions

• AGENTS.md: Agent Constitution file that defines project context, operational boundaries, and command registry for AI agents.
• specs/: Directory containing permanent living specifications for features.
• .plans/: Directory containing transient task-level implementation plans.
• schemas/: Directory containing JSON Schema definitions for validation (Standardized Parts pattern).
• MCP: Model Context Protocol — framework for AI agents to connect to external services.
• Standardized Parts: ASDLC pattern for schema-enforced structure and validation.

Prerequisites

• None required. This command is optional and can be run at any time.
• MCP setup is optional — command will check MCP status but won't block if unavailable.
• Git repository — command works best in a Git repository but doesn't require it.

Purpose

Enable teams to quickly adopt ASDLC patterns by automating initial repository setup. This command creates the foundational structure (AGENTS.md, specs/, .plans/) that supports ASDLC workflows while maintaining flexibility—teams can use other commands without running setup.

Steps

1. Check for existing AGENTS.md

   • Check if AGENTS.md exists in repository root
   • If exists: Report "AGENTS.md already exists, skipping creation"
   • If missing: Proceed to generate template (Step 2)

2. Generate AGENTS.md template (if missing)

   • Read existing AGENTS.md from this repository as template reference (if available)
   • Create AGENTS.md with template structure:
     • Project Mission placeholder: > **Project Mission:** [Your project mission statement]
     • Core Philosophy placeholder: > **Core Philosophy:** [Your core development philosophy]
     • ASDLC Alignment placeholder: > **ASDLC Alignment:** [Your ASDLC alignment statement]
     • Identity & Persona section with placeholders
     • Tech Stack section with placeholders
     • Operational Boundaries (3-tier structure):
       • Tier 1 (ALWAYS): Non-negotiable standards
       • Tier 2 (ASK): High-risk operations requiring Human-in-the-Loop
       • Tier 3 (NEVER): Safety limits
     • Command Registry (empty, to be populated)
     • Development Map (placeholder)
     • Common Pitfalls section (examples)
   • Report: "Created AGENTS.md template"

3. Create specs/ directory

   • Check if specs/ directory exists
   • If exists: Report "specs/ directory already exists, skipping creation"
   • If missing: Create specs/ directory
   • Check if specs/README.md exists
   • If missing: Copy specs/README.md from this repository (if available) or create basic README
   • Report: "Created specs/ directory with README.md"

4. Create .plans/ directory

   • Check if .plans/ directory exists
   • If exists: Report ".plans/ directory already exists, skipping creation"
   • If missing: Create .plans/ directory
   • Create .plans/.gitkeep file to ensure directory is tracked by Git
   • Report: "Created .plans/ directory"

5. Detect if schemas/ directory is needed

   • Check if schemas/ directory exists
   • If exists: Report "schemas/ directory already exists, skipping creation"
   • If missing: Check for schema indicators:
     • If AGENTS.md exists, search for keywords: "Standardized Parts", "schema", "validation"
     • If any keyword found: Create schemas/ directory and schemas/README.md template
     • Report: "Detected need for schemas/ (found: {keyword} in AGENTS.md)" or "No schemas/ needed (no indicators found)"

6. Create schemas/README.md template (if schemas/ was created)

   • Create schemas/README.md with template explaining:
     • When schemas are needed (Standardized Parts pattern)
     • Link to ASDLC Standardized Parts pattern
     • Note: Can be added later if needed
   • Report: "Created schemas/README.md template"

7. Optional: Verify MCP setup (non-blocking)

   • Attempt to run python schemas/validate_mcps.py --list (if available)
   • If successful: Report "MCP setup detected"
   • If fails or unavailable: Report "MCP setup not detected (optional, can be configured later)"
   • Continue regardless of result

8. Optional: Verify issue tracker connection (non-blocking)

   • Attempt to call lightweight MCP tool (e.g., mcp_atlassian_getAccessibleAtlassianResources or mcp_github_list_commits)
   • If successful: Report "Issue tracker connection verified"
   • If fails or unavailable: Report "Issue tracker connection not available (optional, can be configured later)"
   • Continue regardless of result

9. Generate setup summary

   • Report what was created vs skipped
   • Provide next steps guidance:
     • "Next steps: Customize AGENTS.md with your project details"
     • "Configure MCP servers (see docs/reference/mcp-setup.md)"
     • "Create your first spec with /create-plan"

Tools

Filesystem Tools

• read_file - Read existing AGENTS.md and specs/README.md as templates
• write - Create new files (AGENTS.md, specs/README.md, schemas/README.md)
• list_dir - Check if directories exist
• glob_file_search - Find existing files

Terminal Tools

• run_terminal_cmd - Execute commands:
  • python schemas/validate_mcps.py --list (if available) - Check MCP setup
  • git status (optional) - Verify Git repository

MCP Tools (Optional, Non-Blocking)

• mcp_atlassian_getAccessibleAtlassianResources - Verify Atlassian/Jira connection
  • Parameters: None
  • Error handling: If fails, report but continue
• mcp_github_list_commits - Verify GitHub connection
  • Parameters: owner, repo (if available)
  • Error handling: If fails, report but continue

Expected Output

Fresh Repository Setup

🚀 ASDLC Setup Complete

Created:
  ✅ AGENTS.md template
  ✅ specs/ directory with README.md
  ✅ .plans/ directory
  ⚠️  schemas/ not needed (no indicators found)

MCP Status:
  ⚠️  MCP setup not detected (optional, can be configured later)
  ⚠️  Issue tracker connection not available (optional, can be configured later)

Next steps:
  1. Customize AGENTS.md with your project details
  2. Configure MCP servers (see docs/reference/mcp-setup.md)
  3. Create your first spec with /create-plan

Partial Setup (AGENTS.md exists)

🚀 ASDLC Setup Complete

Skipped:
  ⚠️  AGENTS.md already exists

Created:
  ✅ specs/ directory with README.md
  ✅ .plans/ directory
  ✅ schemas/ directory (detected: Standardized Parts in AGENTS.md)

MCP Status:
  ✅ MCP setup detected
  ✅ Issue tracker connection verified

Next steps:
  1. Create your first spec with /create-plan

Full Setup Already Exists

🚀 ASDLC Setup Complete

All directories and files already exist:
  ✅ AGENTS.md
  ✅ specs/ directory
  ✅ .plans/ directory
  ✅ schemas/ directory

MCP Status:
  ✅ MCP setup detected
  ✅ Issue tracker connection verified

Repository is already set up for ASDLC!

When to Use

• New repository - Set up ASDLC structure from scratch
• Existing repository - Add ASDLC structure to existing project
• Team onboarding - Standardize setup across team members
• ASDLC adoption - Begin using ASDLC patterns and workflows

Error Handling

If AGENTS.md template generation fails:

• Report error but continue with directory creation
• Provide manual creation instructions

If directory creation fails:

• Report which directories failed
• Provide manual creation instructions
• Continue with other operations

If MCP verification fails:

• Report warning but continue (MCP is optional)
• Provide MCP setup documentation link

If file copy fails (specs/README.md):

• Create basic README.md with minimal content
• Report that template copy failed

Not