init-workspace

name	init-workspace
description	Use when creating or updating a repository's root AGENTS.md file to provide project-specific guidance for agents
metadata	{"user-invocable":true,"disable-model-invocation":true}

Initialize Workspace Agent Guidance

Create a focused, repository-specific AGENTS.md file that provides project guidance without duplicating mode-specific rules.

Overview

The root AGENTS.md file provides repository-specific standing operating procedures. It works alongside .bob/custom_modes.yaml (mode definitions) and .bob/commands/ (workflow commands), but does NOT duplicate their content.

When to Use

• Setting up a new repository with Bob Superpowers
• Updating existing AGENTS.md that has become stale or duplicative
• Converting generic AGENTS.md to project-specific guidance

When NOT to Use

• Creating mode-specific rules (use .bob/rules-{mode}/AGENTS.md)
• Writing workflow commands (use .bob/commands/)
• Documenting how Superpowers works (that's in mode files)

The Three-File Architecture

Understand what belongs where:

File	Scope	Content
.bob/custom_modes.yaml	Mode definition	Lightweight steering, command awareness
.bob/rules-{mode}/AGENTS.md	Mode behavior	Enforcement rules, anti-patterns, "1% rule"
AGENTS.md (root)	Repository	Project-specific workflows, commands, conventions

Critical: Root AGENTS.md is about THIS PROJECT, not about how modes work.

Anti-Patterns to Avoid

Don't Do This	Why It's Wrong	Do This Instead
Copy .bob/rules-Superpowers/AGENTS.md	Wrong scope - mode rules ≠ project guidance	Reference mode, add project specifics
List all available commands	Duplicates .bob/commands/, gets stale	Reference command directory
Add generic placeholder sections	No value, just noise	Add actual project information or omit
Add TODO/TBD markers	Defers work, creates placeholders	Ask for info now
Include workflow enforcement rules	Belongs in mode-specific rules	Focus on project conventions
Write 100+ lines	Maintenance burden, likely duplicative	Keep focused, 30-50 lines typical

Process

1. Understand Current State

Check what already exists:

• Is there a .bob/custom_modes.yaml? (Superpowers mode defined?)
• Is there a .bob/rules-Superpowers/AGENTS.md? (Mode rules exist?)
• Is there a root AGENTS.md? (If yes, is it duplicative?)

2. Extract Existing Project Content (if applicable)

If root AGENTS.md exists and is duplicative:

• Scan for actual project-specific information:
  • Build/test commands
  • Entry points and architecture notes
  • Coding conventions
  • Dangerous pitfalls or gotchas
• Extract and save this content
• Discard mode rules, command lists, generic placeholders
• Use extracted content in new file

3. Gather Project Information

Ask the user about THIS project:

• What are the build/test commands?
• What are the main entry points?
• Any architecture constraints?
• Any coding conventions?
• Any dangerous pitfalls?
• Any deployment/release notes?

Don't guess. If you don't know, ask.

4. Create Minimal AGENTS.md

Use this template structure:

# AGENTS.md

Repository-specific guidance for agents working in this project.

## Purpose

This file provides project-specific operating guidance. It works alongside:
- `.bob/custom_modes.yaml` - Superpowers mode (always-on command awareness)
- `.bob/commands/` - Detailed workflow commands

## Instruction Priority

1. Direct user instructions (highest)
2. Repository-specific instructions (this file)
3. Bob Superpowers commands
4. Default agent behavior

## Project-Specific Workflows

[Add actual project preferences, e.g.:]
- Prefer `/test-driven-development` for all feature work
- Use `/systematic-debugging` for production issues
- Always run tests before committing

## Build & Test Commands

[Add actual commands for THIS project:]
```bash
# Run tests
npm test

# Build
npm run build

Architecture Notes

[Add actual architecture info:]

• Main entry point: src/index.ts
• Configuration: config/

Coding Conventions

[Add actual conventions:]

• Use TypeScript strict mode
• Keep functions under 50 lines

Repository-Specific Notes

[Add actual gotchas, deployment notes, etc.]

### 5. Keep It Focused

**Good content:**
- Actual build commands for this project
- Actual entry points and architecture
- Actual coding conventions used here
- Actual dangerous pitfalls specific to this codebase

**Bad content:**
- Generic workflow descriptions (that's in commands)
- Mode enforcement rules (that's in mode files)
- Lists of available commands (that's in .bob/commands/)
- Placeholder sections with no real information

### 6. Validate Scope

Before finalizing, check each section:
- Is this specific to THIS repository? ✅ Keep it
- Is this about how Superpowers works? ❌ Remove it (belongs in mode files)
- Is this a generic workflow? ❌ Remove it (belongs in commands)
- Is this a placeholder? ❌ Remove it (add real info or omit section)

## Template

```markdown
# AGENTS.md

Repository-specific guidance for agents working in this project.

## Purpose

This file provides project-specific operating guidance. It works alongside:
- `.bob/custom_modes.yaml` - Superpowers mode (always-on command awareness)
- `.bob/commands/` - Detailed workflow commands

## Instruction Priority

1. Direct user instructions (highest)
2. Repository-specific instructions (this file)
3. Bob Superpowers commands
4. Default agent behavior

## Project-Specific Workflows

[Add your project's preferred workflows]

## Build & Test Commands

[Add your project's actual commands]

## Architecture Notes

[Add your project's architecture information]

## Coding Conventions

[Add your project's coding standards]

## Repository-Specific Notes

[Add project-specific gotchas, deployment notes, etc.]

Common Mistakes

Mistake	Fix
Copying mode rules into root AGENTS.md	Reference mode, don't duplicate
Adding generic placeholders	Add real info or omit section
Listing all commands	Reference .bob/commands/ directory
Writing 100+ lines	Keep focused on project specifics
Guessing project details	Ask user for actual information

Key Principles

• Repository-specific only - If it applies to all projects, it doesn't belong here
• Reference, don't duplicate - Point to mode files and commands, don't copy them
• Actual information - Real commands, real conventions, real gotchas
• Keep it short - 30-50 lines is typical, 100+ means you're duplicating
• Ask, don't guess - Get real project information from the user

Success Criteria

A good root AGENTS.md:

• Contains only repository-specific information
• References (not duplicates) mode files and commands
• Has actual project details (not placeholders)
• Is short and maintainable (typically 30-50 lines)
• Helps agents understand THIS project specifically