setup-asdlc

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
2. Check if AGENTS.md exists in repository root
3. If exists: Report "AGENTS.md already exists, skipping creation"
4. If missing: Proceed to generate template (Step 2)

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

1. Create specs/ directory
2. Check if specs/ directory exists
3. If exists: Report "specs/ directory already exists, skipping creation"
4. If missing: Create specs/ directory
5. Check if specs/README.md exists
6. If missing: Copy specs/README.md from this repository (if available) or create basic README
7. Report: "Created specs/ directory with README.md"

1. Create .plans/ directory
2. Check if .plans/ directory exists
3. If exists: Report ".plans/ directory already exists, skipping creation"
4. If missing: Create .plans/ directory
5. Create .plans/.gitkeep file to ensure directory is tracked by Git
6. Report: "Created .plans/ directory"

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

1. Create schemas/README.md template (if schemas/ was created)
2. Create schemas/README.md with template explaining:
3. When schemas are needed (Standardized Parts pattern)
4. Link to ASDLC Standardized Parts pattern
5. Note: Can be added later if needed
6. Report: "Created schemas/README.md template"

1. Optional: Verify MCP setup (non-blocking)
2. Attempt to run python schemas/validate_mcps.py --list (if available)
3. If successful: Report "MCP setup detected"
4. If fails or unavailable: Report "MCP setup not detected (optional, can be configured later)"
5. Continue regardless of result

1. Optional: Verify issue tracker connection (non-blocking)
2. Attempt to call lightweight MCP tool (e.g., mcp_atlassian_getAccessibleAtlassianResources or mcp_github_list_commits)
3. If successful: Report "Issue tracker connection verified"
4. If fails or unavailable: Report "Issue tracker connection not available (optional, can be configured later)"
5. Continue regardless of result

1. Generate setup summary
2. Report what was created vs skipped
3. Provide next steps guidance:
4. "Next steps: Customize AGENTS.md with your project details"
5. "Configure MCP servers (see docs/reference/mcp-setup.md)"
6. "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