almanac

/almanac — Workspace Initialization

Set up the magician workspace for this project. Run once per project.

What Gets Created

.workspace/
├── shared/           ← committed to git
│   ├── context.md    current team state and open decisions
│   ├── roadmap.md    feature priorities
│   ├── decisions/    architecture decision records
│   ├── specs/        /conjure design specs
│   └── postmortems/  /autopsy outputs
└── local/            ← always gitignored
    ├── prefs.md      per-machine preferences
    └── session.md    last session state

Process

1. Workspace Mode Decision

Use the AskUserQuestion tool with this configuration — do not write any text before calling it:

{
  "questions": [
    {
      "question": "Should .workspace/shared/ be committed to git?",
      "header": "Workspace",
      "multiSelect": false,
      "options": [
        {
          "label": "Shared (Recommended)",
          "description": "Specs, designs, roadmap, and decisions live in .workspace/shared/ and commit to git. Team members pull the same context. Only per-machine prefs stay in .workspace/local/ (always gitignored)."
        },
        {
          "label": "Private",
          "description": "The entire .workspace/ directory is gitignored. Context stays on this machine only — no sharing with teammates via git."
        }
      ]
    }
  ]
}

Wait for reply before creating any directories or files.

2. Create Directory Structure

mkdir -p .workspace/shared/decisions .workspace/shared/specs .workspace/shared/postmortems
mkdir -p .workspace/local

3. Configure .gitignore

Append to .gitignore (or create it):

# Magician workspace (local machine only)
.workspace/local/

If private mode: .workspace/ instead.

4. Create Initial Files

.workspace/shared/context.md:

# Project Context

**Stack:** <from inspector>
**Archetype:** <from inspector>
**Started:** <today's date>

## Open Decisions
(none yet)

## Current Focus
(describe what you're working on)

.workspace/shared/roadmap.md:

# Roadmap

## In Progress
(none yet)

## Planned
(none yet)

## Completed
(none yet)

.workspace/local/prefs.md:

# Local Preferences

disableGit: false
# Set disableGit: true to skip worktrees and PR flow

5. Minimal CLAUDE.md

If no CLAUDE.md exists, create a lean one:

# Project Rules

(Add earned rules here — only what Claude consistently gets wrong.)

Do not write generic best practices. CLAUDE.md should only contain rules specific to this project.

6. Permissions Allowlist

Build the suggested list based on detected stack. Then use the AskUserQuestion tool — do not write any text before calling it:

{
  "questions": [
    {
      "question": "Add permission rules to .claude/settings.json so Claude Code doesn't prompt for approval on routine operations?",
      "header": "Permissions",
      "multiSelect": false,
      "options": [
        {
          "label": "Add all (Recommended)",
          "description": "Three groups: (1) Core — git commands and reading any project file; (2) Workspace — writing specs, designs, and decision records to .workspace/**, reading session state, resetting event logs between visual companion screens; (3) Stack tools — the build/test/lint commands for your detected stack (npm, pytest, go, etc.). These cover everything Magician does routinely so you never see an approval prompt mid-flow."
        },
        {
          "label": "Choose",
          "description": "I'll show each group separately so you can pick which ones to add."
        },
        {
          "label": "Skip",
          "description": "No rules added. You'll approve each git command, file read, and workspace write individually."
        }
      ]
    }
  ]
}

Wait for reply before writing to settings.json.

If Add all: first ask about Playwright access — use AskUserQuestion with this exact configuration:

{
  "questions": [
    {
      "question": "Which Playwright tools should Claude have access to?",
      "header": "Playwright",
      "multiSelect": false,
      "options": [
        {
          "label": "Grant all playwright",
          "description": "mcp__playwright__* — allows all current and future Playwright tools automatically without listing each one."
        },
        {
          "label": "Grant suggested (Recommended)",
          "description": "The 5 tools used by this plugin: navigate, take_screenshot, wait_for, snapshot, close."
        },
        {
          "label": "Grant specific",
          "description": "Choose which Playwright tool groups to allow — I'll ask you to pick from grouped categories with descriptions."
        }
      ]
    }
  ]
}

If Grant specific: follow up with:

{
  "questions": [
    {
      "question": "Which Playwright tool groups do you want to allow?",
      "header": "Playwright",
      "multiSelect": true,
      "options": [
        {
          "label": "Navigation",
          "description": "browser_navigate, browser_navigate_back, browser_wait_for, browser_tabs — browse to URLs, go back, wait for conditions, manage browser tabs"
        },
        {
          "label": "Screenshots",
          "description": "browser_take_screenshot, browser_snapshot — capture visual state and accessibility tree of pages"
        },
        {
          "label": "Interaction",
          "description": "browser_click, browser_type, browser_fill_form, browser_press_key, browser_hover, browser_drag, browser_select_option — simulate user input and mouse actions"
        },
        {
          "label": "Inspection",
          "description": "browser_evaluate, browser_run_code, browser_console_messages, browser_network_requests, browser_file_upload, browser_resize, browser_handle_dialog, browser_close — execute JS, inspect network traffic, handle dialogs, control browser state"
        }
      ]
    }
  ]
}

Determine playwright_rules from the answer:

• Grant all playwright → ["mcp__playwright__*"]
• Grant suggested → ["mcp__playwright__browser_navigate", "mcp__playwright__browser_take_screenshot", "mcp__playwright__browser_wait_for", "mcp__playwright__browser_snapshot", "mcp__playwright__browser_close"]
• Grant specific → combine rules for each selected group:
  • Navigation: ["mcp__playwright__browser_navigate", "mcp__playwright__browser_navigate_back", "mcp__playwright__browser_wait_for", "mcp__playwright__browser_tabs"]
  • Screenshots: ["mcp__playwright__browser_take_screenshot", "mcp__playwright__browser_snapshot"]
  • Interaction: ["mcp__playwright__browser_click", "mcp__playwright__browser_type", "mcp__playwright__browser_fill_form", "mcp__playwright__browser_press_key", "mcp__playwright__browser_hover", "mcp__playwright__browser_drag", "mcp__playwright__browser_select_option"]
  • Inspection: ["mcp__playwright__browser_evaluate", "mcp__playwright__browser_run_code", "mcp__playwright__browser_console_messages", "mcp__playwright__browser_network_requests", "mcp__playwright__browser_file_upload", "mcp__playwright__browser_resize", "mcp__playwright__browser_handle_dialog", "mcp__playwright__browser_close"]

Then write the full set to .claude/settings.json:

import json, os

path = ".claude/settings.json"
s = json.load(open(path)) if os.path.exists(path) else {}
s.setdefault("permissions", {}).setdefault("allow", [])

# playwright_rules determined by AskUserQuestion above
playwright_rules = [...]  # replace with actual list from user's answer

# Always
base = [
    "Bash(git *)",
    "Read(**)",
    "Write(.workspace/**)",
    "Read(.workspace/**)",
    "Bash(> .workspace/**)",
    "Bash(mkdir* .workspace/**)",
    "Bash(bash *conjure/scripts/vc-*.sh*)",
    "Bash(node *conjure/scripts/server.cjs*)",
    "Bash(open http://localhost:*)",
] + playwright_rules
# Stack-specific (add only what was detected)
stack_rules = {
    "javascript": ["Bash(npm *)", "Bash(npx *)"],
    "python":     ["Bash(pytest *)", "Bash(ruff *)", "Bash(pip *)"],
    "go":         ["Bash(go *)"],
    "rust":       ["Bash(cargo *)"],
    "java":       ["Bash(mvn *)", "Bash(gradle *)"],
}
# DETECTED_STACK comes from inspector additionalContext
detected = []  # fill from inspector context
for tech, rules in stack_rules.items():
    if tech in detected:
        base.extend(rules)

for r in base:
    if r not in s["permissions"]["allow"]:
        s["permissions"]["allow"].append(r)

os.makedirs(".claude", exist_ok=True)
json.dump(s, open(path, "w"), indent=2)
print("Permissions saved.")

If Choose: present each group with its own AskUserQuestion call (core, workspace, stack tools) — one at a time, wait for each reply.

If Skip: continue. Do not ask again this session.

7. MCP Suggestions

Based on detected archetype, suggest relevant MCPs:

• web: browser automation MCP for UI testing
• data: notebook MCP for Jupyter integration
• devops: cloud provider CLI MCPs

Ask: "Want me to set up any of these MCPs? If so, which ones?" End your turn. Wait for their reply before proceeding to step 8.

8. Save Strategy

Record workspace mode:

python3 -c "
import json, os
data = {'ignored': 'true', 'mode': 'shared'}
path = os.path.expanduser('~/.local/share/magician/workspace-strategy.json')
os.makedirs(os.path.dirname(path), exist_ok=True)
json.dump(data, open(path,'w'))
print('Strategy saved.')
"

9. Commit (if shared mode)

git add .workspace/shared/ CLAUDE.md .gitignore
git commit -m "chore: initialize magician workspace"

Completion Signal

"Almanac complete. Workspace initialized in mode. Run /conjure to start designing, or /manifest for the full flow."