[!] DEPRECATED: Use maestro symphony install --linear-project <slug> instead. This skill will be removed in a future release.

Symphony Setup -- Automated Project Onboarding

Set up OpenAI Symphony orchestration for the current repository so that Codex agents can autonomously pick up Linear issues, implement them, create PRs, and land them.

This skill handles:

• Environment and prerequisite validation
• Brownfield detection (existing configs, partial setups)
• Codex skill installation with conflict resolution
• WORKFLOW.md generation from project context
• Linear integration verification
• End-to-end setup validation

Arguments

$ARGUMENTS

Two arguments:

1. Linear project slug (required) -- from the project URL (e.g., my-project-abc123). Right-click the project in Linear, copy URL, extract the slug after /project/.
2. Repo clone URL (optional) -- the git clone URL (e.g., https://github.com/org/repo.git). If omitted, detected from git remote get-url origin.

If the Linear project slug is missing, ask the user for it. Do not proceed without it.

Step 1: Validate Prerequisites

Check each prerequisite individually. Report all failures at once (do not stop at the first).

1a: Environment detection

uname -s          # Darwin or Linux
echo "$SHELL"     # Shell type (zsh, bash)
git --version     # Git must be available
python3 --version # Required for land_watch.py

Record OS and shell for later command compatibility (e.g., open vs xdg-open for URLs).

1b: Required tools

1c: Required environment variables

1d: Symphony service

Check if Symphony is available:

ls ~/Code/symphony/bin/symphony 2>/dev/null || echo "not found"

If not found, warn but do not block -- the user may run Symphony from a different location or start it later.

1e: Repository validation

Confirm the current directory is a git repository with a remote:

git rev-parse --is-inside-work-tree  # Must be true
git remote get-url origin            # Must return a URL

If no remote exists, ask the user for the repo clone URL (second argument).

Step 1 output

Print a prerequisites summary:

Prerequisites Check
===================
[ok] git 2.43.0
[ok] codex 1.2.3
[ok] python3 3.12.1
[ok] gh 2.40.0
[ok] LINEAR_API_KEY set
[ok] OPENAI_API_KEY set
[!!] Symphony not found at ~/Code/symphony/ (non-blocking)
[ok] Git repository with remote: https://github.com/org/repo.git

{N} passed, {M} failed, {K} warnings

If any required check fails, print fix instructions and stop. Do not proceed with a broken environment.

Step 2: Detect Project State

Determine whether this is a fresh setup or a brownfield (partial/existing configuration).

See reference/environment-detection.md for detection logic, indicators, and migration patterns.

2a: Check for existing Symphony/Codex configuration

# Existing Codex skills
ls .codex/skills/*/SKILL.md 2>/dev/null

# Existing workflow file
ls WORKFLOW.md 2>/dev/null

# Existing Codex config
ls CODEX.md .codex/CODEX.md 2>/dev/null

# Existing agent configs (may contain relevant rules)
ls CLAUDE.md AGENTS.md 2>/dev/null

2b: Classification and routing

For Partial and Complete states, ask the user before overwriting any existing files.

2c: Existing file inventory

If existing Codex skills are found, list them and compare against the expected set (commit, debug, land, linear, pull, push). Identify:

• Missing skills (will be installed)
• Extra skills (will be preserved)
• Modified skills (warn, ask before overwriting)

Step 3: Gather Project Context

Read the project's existing documentation and configuration to populate the WORKFLOW.md template. This step produces a structured context object used in Step 5.

3a: Documentation sources

Read these files (whichever exist), in priority order:

3b: Git metadata

git remote get-url origin                    # Repo URL
git rev-parse --abbrev-ref HEAD              # Primary branch (main/master)
basename $(git rev-parse --show-toplevel)    # Project directory name
git log --oneline -5                         # Recent activity (brownfield indicator)

3c: Build/test command detection

Search for build and test commands in this priority order:

1. Explicit in CLAUDE.md/AGENTS.md -- highest priority, use as-is
2. Package manifest scripts -- package.json scripts, Makefile targets, Cargo.toml profiles
3. CI configuration -- GitHub Actions steps, commands in workflow files
4. Convention -- infer from tech stack (e.g., bun test for Bun projects, cargo test for Rust)

See reference/environment-detection.md for tech stack detection heuristics and default commands per stack.

3d: Structured output

Assemble the collected data into this structure (used in Step 5):

project_name:        <from README or directory name>
project_description: <2-3 sentences from README or ask user>
repo_url:            <from git remote or argument>
primary_branch:      <main or master>
build_commands:      <list of build/test/lint commands>
project_rules:       <list of coding rules and conventions>
tech_stack:          <languages, frameworks, tools>

If any required field cannot be determined, ask the user. Do not leave placeholders in the final output.

Step 4: Install Codex Skills

Copy the Symphony skill templates into .codex/skills/ in the target repository.

See reference/codex-skills-guide.md for detailed documentation on what each skill does, how they relate to each other, and customization patterns.

4a: What Codex skills are

Codex skills are markdown instruction files that the Codex CLI loads to guide agent behavior during specific operations. They live in .codex/skills/<name>/SKILL.md and are automatically available to the agent during Symphony sessions.

The Symphony skill set provides six skills that form an autonomous development workflow:

4b: Install the skills

The templates are bundled at reference/codex-skills/. Create the directory structure and copy:

mkdir -p .codex/skills/{commit,debug,land,linear,pull,push}

Copy each skill file from reference/codex-skills/ to .codex/skills/:

reference/codex-skills/commit/SKILL.md  -->  .codex/skills/commit/SKILL.md
reference/codex-skills/debug/SKILL.md   -->  .codex/skills/debug/SKILL.md
reference/codex-skills/land/SKILL.md    -->  .codex/skills/land/SKILL.md
reference/codex-skills/land/land_watch.py --> .codex/skills/land/land_watch.py
reference/codex-skills/linear/SKILL.md  -->  .codex/skills/linear/SKILL.md
reference/codex-skills/pull/SKILL.md    -->  .codex/skills/pull/SKILL.md
reference/codex-skills/push/SKILL.md    -->  .codex/skills/push/SKILL.md

4c: Conflict resolution

If .codex/skills/ already has files:

1. Identical content -- skip silently
2. Different content -- show a diff summary and ask:
   • Overwrite -- replace with Symphony template
   • Keep existing -- preserve the current file
   • Merge -- show both versions side by side, let user choose sections
3. Extra skills (not in the Symphony set) -- preserve them, do not touch

4d: Make land_watch.py executable

chmod +x .codex/skills/land/land_watch.py

4e: Verification

# Confirm all expected files exist
ls .codex/skills/commit/SKILL.md \
   .codex/skills/debug/SKILL.md \
   .codex/skills/land/SKILL.md \
   .codex/skills/land/land_watch.py \
   .codex/skills/linear/SKILL.md \
   .codex/skills/pull/SKILL.md \
   .codex/skills/push/SKILL.md

Print install summary: {N} skills installed, {M} skipped (existing), {K} conflicts resolved.

Step 5: Generate WORKFLOW.md

Use the template at reference/WORKFLOW.md.template as the base. Replace placeholders with the context gathered in Step 3.

See reference/workflow-customization.md for detailed guidance on each section and customization options.

5a: Placeholder replacement

5b: Quality checks before writing

Before writing WORKFLOW.md, verify:

1. No unreplaced {{...}} placeholders remain
2. The project_description is substantive (not just the project name repeated)
3. At least one build/test command is included
4. Project rules are formatted as a markdown list

If any check fails, ask the user to provide the missing information.

5c: Write the file

Write the result to WORKFLOW.md in the repository root.

If WORKFLOW.md already exists:

• Show a diff summary of changes
• Ask: Overwrite / Backup and overwrite (saves to WORKFLOW.md.bak) / Cancel

5d: Validate YAML front matter

The WORKFLOW.md template begins with YAML front matter. Confirm it parses correctly:

head -20 WORKFLOW.md | grep -c "^---"  # Should be 2 (opening and closing)

Step 6: Configure Linear Integration

Verify the Linear project is accessible and has the required custom statuses.

See reference/linear-setup.md for detailed Linear configuration guidance.

6a: Verify Linear project access

Use the Linear MCP or API to confirm the project slug resolves:

Query: project by slug "{{PROJECT_SLUG}}"
Expected: project name, team, URL

If the project is not found, ask the user to verify the slug. Common issues:

• Slug includes extra URL path segments
• Project is in a different workspace
• API key lacks access to the project's team

6b: Check required custom statuses

Symphony requires three non-standard Linear issue statuses. Check if they exist in the team's workflow:

Query the team's workflow states and check for each required status.

6c: Report and guide

If all statuses exist:

[ok] Linear project "{project_name}" accessible
[ok] Status "Rework" (started) exists
[ok] Status "Human Review" (started) exists
[ok] Status "Merging" (started) exists

If any are missing, provide step-by-step creation instructions:

[!!] Missing Linear statuses. Create them in Team Settings:

1. Open Linear --> Settings --> Teams --> {team_name} --> Workflow
2. Under "Started" states, click "Add status"
3. Create each missing status:
   - Name: "Rework"       | Type: Started | Description: "Agent addressing review feedback"
   - Name: "Human Review"  | Type: Started | Description: "PR ready for human review"
   - Name: "Merging"       | Type: Started | Description: "Agent merging approved PR"
4. Save changes

After creating the statuses, re-run this step to verify.

Step 7: Verify Setup

Run a structured verification of the entire setup. Each check is pass/fail with specific recovery guidance.

7a: File integrity checks

7b: Environment checks

7c: Integration checks

7d: Verification summary

Setup Verification
==================
File integrity:    {N}/7 passed
Environment:       {N}/5 passed
Integration:       {N}/3 passed

Overall: {PASS|FAIL} ({total_passed}/{total_checks})

If all checks pass, proceed to Step 8. If any fail, print the recovery steps and stop.

Step 8: Report and Next Steps

Print a comprehensive setup summary with clear next steps.

Symphony Setup Complete
=======================

Repository:       {repo_name}
Linear project:   {project_slug}
Primary branch:   {primary_branch}
Skills installed: commit, debug, land, linear, pull, push
WORKFLOW.md:      created
Linear statuses:  {verified|manual setup needed}

Verification: {total_passed}/{total_checks} checks passed

Next steps:

1. Commit the new files:
   git add .codex/skills/ WORKFLOW.md
   git commit -m "feat: add Symphony workflow and Codex skills"

2. Start Symphony:
   cd ~/Code/symphony
   ./bin/symphony /path/to/WORKFLOW.md --port 4000

3. Create a test issue in Linear (assign to the project)
   - Symphony will pick it up and start working

4. Monitor the first run:
   - Watch the Symphony terminal for status updates
   - Check Linear issue status transitions
   - Use the debug skill if a run gets stuck

Troubleshooting:
- Symphony not picking up issues?  Check LINEAR_API_KEY and project slug
- Codex errors?                    Check OPENAI_API_KEY and codex version
- PR creation fails?               Check gh auth status
- land_watch.py fails?             Check python3 and gh CLI availability
- Stuck in "In Progress"?          Use the debug skill to inspect logs

Notes

• The linear skill requires Symphony's linear_graphql app-server tool -- it only works during active Symphony sessions. Outside of Symphony, use Linear MCP or the web UI.
• The land skill uses land_watch.py to monitor PR status asynchronously. It polls GitHub for CI status, review comments, and head changes. Requires Python 3 and the gh CLI.
• The debug skill is for troubleshooting Symphony/Codex log issues -- not needed for normal operation but invaluable for diagnosing stuck runs.
• Symphony depends on non-standard Linear issue statuses (Rework, Human Review, Merging). These must be added manually in Linear Team Settings --> Workflow. See reference/linear-setup.md.
• The WORKFLOW.md template includes a ticket state machine that drives all agent behavior. See reference/workflow-customization.md for customization guidance.

Relationship to Other Skills

Symphony setup is complementary to maestro setup. Maestro manages human-orchestrated multi-agent workflows; Symphony manages fully autonomous single-agent issue resolution. They can coexist in the same repository.