setup-ai-workspace

Setup AI Workspace

Goal: create the smallest useful AI operating layer for the current project or domain.

Process

1. Inspect first:
   • Existing AGENTS.md, CLAUDE.md, .codex/, .claude/, plugins/, workspace manifests, app folders, package boundaries, and docs.
   • If the answer is in the codebase, use it instead of asking.
2. Ask one question at a time only when the decision cannot be inferred.
3. For every question, include a recommended answer and one-sentence reason.
4. Produce a setup profile before writing files.
5. If the user asked to apply the setup, write files surgically and verify them.

Required Questions

Ask in this order unless already answered:

1. Depth: low, medium, high, or max.
2. Scope: current project, global user setup, or both.
3. Topology: single project, monorepo/workspace, multi-repo domain, or unknown.
4. Domains present: backend, frontend, mobile, data, infra, design, product, docs, security.
5. Skills: none, project-local, global, or both.
6. Agents: none, project-local, global, reuse spotify-squad, or hybrid.
7. Contract files: canonical AGENTS.md, CLAUDE.md symlink, pointer file, or preserve existing split.
8. Handoff: no handoff, temp handoff, or project handoff artifact.

Depth Matrix

• low: root AGENTS.md/CLAUDE.md, setup profile, basic verification.
• medium: low plus project skills, routing rules, quality gates.
• high: medium plus orchestrator agent, domain subagents, skill map.
• max: high plus cross-repo/domain map, handoff loop, review loop, refinement cadence.

Output Contract

Return:

1. Setup Profile: depth, scope, topology, domains.
2. Artifacts: files to create/update, with global vs project placement.
3. Skill Plan: skill names, triggers, scope, why each exists.
4. Agent Plan: orchestrator, subagents, delegation model.
5. Contract Plan: AGENTS/CLAUDE strategy and symlink/pointer decision.
6. Verification: exact checks to prove setup is complete.

Rules

• Do not create speculative agents or skills.
• Prefer project-local skills for repo conventions and global skills for reusable workflows.
• For monorepos, create one root orchestrator that delegates to app/domain agents.
• For separate backend/frontend/mobile repos in one domain, create one domain orchestrator and link each repo contract back to it.
• Preserve existing instructions; append a delimited block instead of rewriting unrelated content.
• If a symlink is requested but unsupported or risky, create a short pointer file and explain the tradeoff.