Phase 2: Smart para-init - File-Based Setup Scripts

[brian-lai]

🎯 Phase 2: File-Based Setup Scripts

This PR implements the actual file creation logic for PARA-Programming setup, completing the smart initialization system started in Phase 1.

Plan: context/plans/2026-02-02-smart-para-init-auto-detection.md
Branch: para/smart-para-init-phase-2
Phase: 2 of 4

---

📦 What's Included

1. Master Template (templates/AGENTS.md - 408 lines)

Complete PARA-Programming methodology template used by setup scripts:

• Five-step workflow: Plan → Review → Execute → Summarize → Archive
• Decision tree: When to use PARA vs. skip
• Context directory structure and file naming conventions
• Token efficiency principles
• Tool integration guidance (MCP, preprocessing)
• Git workflow with commit-per-todo pattern
• Quality checklist and error handling

This becomes the single source of truth for AGENTS.md across all projects.

2. Tier 1 Setup Script (scripts/setup-tier1.sh - 88 lines)

For: Cursor, Continue.dev (Full PARA Support)

Creates AGENTS.md without symlinks (tools read it natively):

./scripts/setup-tier1.sh [--verbose]

Features:

• Copies AGENTS.md from templates/AGENTS.md
• Checks if AGENTS.md already exists (skips if present)
• Sets correct permissions (644)
• Verbose mode for debugging
• Returns proper exit codes

Output:

  ✓ Created AGENTS.md

3. Tier 2 Setup Script (scripts/setup-tier2.sh - 162 lines)

For: GitHub Copilot, Gemini (Methodology Only)

Creates AGENTS.md + symlinks (tools need specific file locations):

./scripts/setup-tier2.sh [--tool=copilot|gemini] [--verbose]

Features:

• Creates AGENTS.md from template (if needed)
• Creates .github/ directory for Copilot
• Creates relative symlinks:
  • .github/copilot-instructions.md → ../AGENTS.md
  • GEMINI.md → AGENTS.md
• Checks for existing files and symlinks (skips if present)
• Supports selective setup with --tool=copilot|gemini
• Verbose mode for debugging

Output:

  ✓ Created AGENTS.md
  ✓ Created .github/copilot-instructions.md → ../AGENTS.md (symlink)
  ✓ Created GEMINI.md → AGENTS.md (symlink)

4. Integration into para-init

Updated: setup_file_based_tools() function in scripts/para-init

Replaced placeholder with actual implementation:

• Calls setup-tier1.sh for Tier 1 tools
• Calls setup-tier2.sh for Tier 2 tools
• Displays clear success messages per tool
• Shows tool capabilities (full vs. methodology-only)
• Provides appropriate next steps per tool type

Example output:

$ para-init

PARA-Programming Setup

Detecting AI coding tools...
✓ Found: Claude Code
✓ Found: Cursor
✓ Found: GitHub Copilot

Claude Code uses a native plugin for PARA-Programming.
Install: https://github.com/brian-lai/para-programming-plugin

Setting up PARA-Programming...
  ✓ Cursor configured
  ✓ GitHub Copilot configured

✅ Setup complete!

Tool Capabilities:
  • Cursor: Full PARA workflow with slash commands, multi-file editing
  • GitHub Copilot: PARA methodology (manual workflow, no slash commands)

Next Steps:
  1. Restart your IDE to load the new configuration
  2. In Cursor: Try slash commands like /para:plan
  3. See AGENTS.md for complete methodology

---

✅ Success Criteria Met

• ✅ Tier 1 creates AGENTS.md without symlinks
• ✅ Tier 2 creates AGENTS.md + proper symlinks
• ✅ Files have correct permissions (644)
• ✅ Symlinks use relative paths (not absolute)
• ✅ End-to-end flow tested and working
• ✅ Idempotence verified (safe to run multiple times)

---

🧪 Testing

Test 1: Tier 1 Setup (Cursor)

$ ./scripts/setup-tier1.sh --verbose
[setup-tier1] Starting Tier 1 setup...
[setup-tier1] Template path: .../templates/AGENTS.md
[setup-tier1] Target path: .../AGENTS.md
[setup-tier1] Copying template to .../AGENTS.md
[setup-tier1] Set permissions: 644
  ✓ Created AGENTS.md

✅ Result: AGENTS.md created with correct content and permissions

Test 2: Tier 2 Setup (Copilot + Gemini)

$ ./scripts/setup-tier2.sh --verbose
[setup-tier2] Starting Tier 2 setup...
[setup-tier2] Creating .github directory
[setup-tier2] Creating symlink: .../copilot-instructions.md -> ../AGENTS.md
[setup-tier2] Creating symlink: .../GEMINI.md -> AGENTS.md
  ✓ Created AGENTS.md
  ✓ Created .github/copilot-instructions.md → ../AGENTS.md (symlink)
  ✓ Created GEMINI.md → AGENTS.md (symlink)

✅ Result: AGENTS.md + both symlinks created with relative paths

Test 3: Symlink Verification

$ ls -la .github/copilot-instructions.md GEMINI.md
lrwxr-xr-x  .github/copilot-instructions.md -> ../AGENTS.md
lrwxr-xr-x  GEMINI.md -> AGENTS.md

✅ Result: Both symlinks use relative paths (not absolute)

Test 4: End-to-End para-init

$ ./scripts/para-init
[Detects: Claude Code, Cursor, Copilot, Gemini]
[Shows Claude plugin instructions]
[Creates AGENTS.md and symlinks]
[Displays capabilities and next steps]
✅ Setup complete!

✅ Result: Full flow works, all tools configured correctly

Test 5: Idempotence

$ ./scripts/para-init
  ⚠️  AGENTS.md already exists (skipping)
  ⚠️  .github/copilot-instructions.md already exists (skipping)
  ⚠️  GEMINI.md already exists (skipping)
✅ Setup complete!

✅ Result: Running twice is safe, existing files detected and skipped

---

📝 Implementation Notes

Design Decisions

1. Templates Directory

Created templates/ to hold the master AGENTS.md template. This provides:

• Single source of truth for AGENTS.md content
• Easy to update methodology across all tools
• Clear separation between template and user files

2. Separate Tier Scripts

Split into setup-tier1.sh and setup-tier2.sh because:

• Different tools have fundamentally different setup needs
• Tier 1: Just copy AGENTS.md
• Tier 2: Copy AGENTS.md + create symlinks
• Easier to test and debug separately

3. Relative Symlinks

Always use relative paths (never absolute) because:

• Works when project is moved or cloned
• Platform-independent (works on macOS, Linux, Windows with symlink support)
• Git tracks relative symlinks correctly

4. Idempotence by Design

All scripts check for existing files before creating:

• Users can safely run para-init multiple times
• Useful for adding new tools later
• Prevents accidental overwrites

File Structure

para-programming/
├── templates/
│   └── AGENTS.md                      # Master template (408 lines)
├── scripts/
│   ├── detect-tools.sh                # Phase 1 (detection)
│   ├── para-init                      # Phase 1 + Phase 2 (orchestration)
│   ├── setup-tier1.sh                 # Phase 2 (Tier 1 setup)
│   └── setup-tier2.sh                 # Phase 2 (Tier 2 setup)
└── .github/
    └── copilot-instructions.md -> ../AGENTS.md  (created by setup)

---

🔄 What's Next

Phase 3: User Experience & Display

• Interactive selection menu for multiple tools
• Enhanced progress indicators and status messages
• Tool-specific "next steps" guidance improvements

Phase 2 establishes the core file creation logic. Phase 3 will polish the UX.

---

🚀 Ready for Review

This PR is complete and ready for review. Phase 2 delivers on the promise of smart, automatic setup.

Review checklist:

• Template content is comprehensive and accurate
• Tier 1 setup creates files correctly
• Tier 2 setup creates symlinks with relative paths
• Integration into para-init works smoothly
• Idempotence is verified
• Error handling is robust

---

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com