docs(workflow): rename workspace context paths to tmp

d-padmanabhan · d-padmanabhan · commit 56b5bf623139 · 2026-02-16T13:27:42.000-05:00
diff --git a/.gitignore b/.gitignore
@@ -60,4 +60,4 @@ htmlcov/
 .pytest_cache/
 
 # Private/local documentation
-extras/
+tmp/
diff --git a/NEW_REPO_CHECKLIST.md b/NEW_REPO_CHECKLIST.md
@@ -24,31 +24,31 @@ readlink .cursor/rules
 
 ## Setup workspace context files
 
-- [ ] Create `extras/` (workspace-local, gitignored)
-- [ ] Create `extras/tasks.md` (minimum)
+- [ ] Create `tmp/` (workspace-local, gitignored)
+- [ ] Create `tmp/tasks.md` (minimum)
 
 ```bash
-mkdir -p extras
-cp .cursor/rules/templates/tasks.md.template extras/tasks.md
+mkdir -p tmp
+cp .cursor/rules/templates/tasks.md.template tmp/tasks.md
 ```
 
 Optional (for complex work):
 
-- [ ] `extras/project-brief.md`
-- [ ] `extras/active-context.md`
-- [ ] `extras/progress.md`
+- [ ] `tmp/project-brief.md`
+- [ ] `tmp/active-context.md`
+- [ ] `tmp/progress.md`
 
 ```bash
-cp .cursor/rules/templates/project-brief.md.template extras/project-brief.md
-cp .cursor/rules/templates/active-context.md.template extras/active-context.md
-cp .cursor/rules/templates/progress.md.template extras/progress.md
+cp .cursor/rules/templates/project-brief.md.template tmp/project-brief.md
+cp .cursor/rules/templates/active-context.md.template tmp/active-context.md
+cp .cursor/rules/templates/progress.md.template tmp/progress.md
 ```
 
 ## Git hygiene (recommended)
 
-- [ ] Ensure `extras/` is ignored (add to your repo’s `.gitignore`):
+- [ ] Ensure `tmp/` is ignored (add to your repo’s `.gitignore`):
 
 ```gitignore
 # Private/local documentation
-extras/
+tmp/
 ```
diff --git a/SETUP_GUIDE.md b/SETUP_GUIDE.md
@@ -5,7 +5,7 @@ description: Setup Cursor rules + workspace context templates using symlinks or
 
 # Setup Guide
 
-This repo is designed to be used across many projects via a **shared rules directory** (symlink/submodule). Workspace context files stay **workspace-local** under `extras/` (gitignored).
+This repo is designed to be used across many projects via a **shared rules directory** (symlink/submodule). Workspace context files stay **workspace-local** under `tmp/` (gitignored).
 
 ## Recommended setup (team)
 
@@ -50,9 +50,9 @@ Templates live at:
 
 Workspace context files should live at:
 
-- `extras/tasks.md`
-- `extras/active-context.md`
-- `extras/progress.md`
-- `extras/project-brief.md`
+- `tmp/tasks.md`
+- `tmp/active-context.md`
+- `tmp/progress.md`
+- `tmp/project-brief.md`
 
 See `rules/050-workflow.mdc` for the workflow and file meanings.
diff --git a/commands/archive.md b/commands/archive.md
@@ -36,9 +36,9 @@ Document the completed task, capture lessons learned, and update the knowledge b
    - Any gotchas or surprises?
 
 4. **Update Context Files**
-   - Update `extras/progress.md` with completion status
-   - Create `extras/reflect-<task>.md` if significant learnings
-   - Update `extras/tasks.md` to mark task complete
+   - Update `tmp/progress.md` with completion status
+   - Create `tmp/reflect-<task>.md` if significant learnings
+   - Update `tmp/tasks.md` to mark task complete
 
 5. **Identify Reusable Patterns**
    - Any patterns that should be standardized?
@@ -98,8 +98,8 @@ Document the completed task, capture lessons learned, and update the knowledge b
 
 Save archives to:
 
-- `extras/reflect-<task-name>.md` - For significant tasks
-- Or update `extras/progress.md` - For simpler summaries
+- `tmp/reflect-<task-name>.md` - For significant tasks
+- Or update `tmp/progress.md` - For simpler summaries
 
 ## Skip When
 
diff --git a/commands/check-progress.md b/commands/check-progress.md
@@ -172,12 +172,12 @@ Propose **one primary commit message** following `110-git.mdc` format:
 
 ## Phase 6: Task Management
 
-1. Create or update `<repo-root>/extras/TODO.md` with:
+1. Create or update `<repo-root>/tmp/TODO.md` with:
    - Remaining tasks
    - Edge cases
    - Follow-ups and future improvements
 
-2. Ensure `extras/` is present in `.gitignore`. Add it if missing.
+2. Ensure `tmp/` is present in `.gitignore`. Add it if missing.
 
 ## Constraints
 
diff --git a/commands/code-commit.md b/commands/code-commit.md
@@ -150,11 +150,11 @@ And ask:
 
 ---
 
-## Step 6: Write commit message file under `extras/commit_messages`
+## Step 6: Write commit message file under `tmp/commit_messages`
 
 Create the commit message file:
 
-- Directory: `extras/commit_messages` (create if missing)
+- Directory: `tmp/commit_messages` (create if missing)
 - Filename format:
   - `YYYYMMDD_HHMMSS_<repo>_<branch>_<last7sha>.md`
   - Example: `20251228_154700_cursor-engineering-rules_main_abcd123.md`
@@ -164,7 +164,7 @@ Notes:
 - Use repo name from `basename "$(git rev-parse --show-toplevel)"`
 - Use branch name from `git branch --show-current`
 - Use last 7 of current HEAD via `git rev-parse --short=7 HEAD`
-- Ensure `extras/` is gitignored before writing artifacts
+- Ensure `tmp/` is gitignored before writing artifacts
 
 > [!NOTE]
 > You cannot know the new commit hash until after committing. If desired, copy/rename the message file after commit to include the new commit short hash.
@@ -175,7 +175,7 @@ Notes:
 
 Commit:
 
-- `git commit -F extras/commit_messages/<filename>.md`
+- `git commit -F tmp/commit_messages/<filename>.md`
 
 Confirm:
 
diff --git a/commands/creative.md b/commands/creative.md
@@ -38,7 +38,7 @@ Required for:
    - Outline implementation approach
 
 5. **Document Decision**
-   - Create `creative-*.md` in extras/ folder
+   - Create `creative-*.md` in tmp/ folder
    - Update `tasks.md` with design decisions
 
 ## Output Format
diff --git a/commands/init.md b/commands/init.md
@@ -16,7 +16,7 @@ Initialize a new task by analyzing the project and determining the appropriate w
    - Scan project structure
    - Identify tech stack and patterns
    - Note existing conventions
-   - Check for existing context files (`extras/prd.md`, `extras/design.md`, `extras/project-brief.md`, `extras/tasks.md`, `extras/active-context.md`)
+   - Check for existing context files (`tmp/prd.md`, `tmp/design.md`, `tmp/project-brief.md`, `tmp/tasks.md`, `tmp/active-context.md`)
 
 2. **Understand the Request**
    - What is the user asking for?
@@ -33,8 +33,8 @@ Initialize a new task by analyzing the project and determining the appropriate w
    | 4 | Complex | Architectural, cross-cutting, multi-day | `/plan` -> `/creative` -> `/qa` -> `/build` -> `/review` -> `/archive` |
 
 4. **Set Up Context**
-   - Create/update `extras/tasks.md` if needed
-   - Create/update `extras/active-context.md` if needed
+   - Create/update `tmp/tasks.md` if needed
+   - Create/update `tmp/active-context.md` if needed
    - Note any existing progress
 
 5. **Route to Next Command**
diff --git a/commands/kbcommit.md b/commands/kbcommit.md
@@ -115,11 +115,11 @@ LONG_DTTM="$(TZ=America/New_York date "+%A, %B %d, %Y @ %l:%M %p ET" | sed 's/
 
 ---
 
-## Step 6: Write commit message file under `kb/extras/commit_messages`
+## Step 6: Write commit message file under `kb/tmp/commit_messages`
 
 Create the commit message file:
 
-- Directory: `extras/commit_messages`
+- Directory: `tmp/commit_messages`
 - Filename format:
   - `YYYYMMDD_HHMMSS_kb_<branch>_<last7sha>.md`
   - Example: `20251228_154700_kb_main_abcd123.md`
@@ -138,7 +138,7 @@ Commit using the file, and add the timestamp trailer:
 ```bash
 set -euo pipefail
 LONG_DTTM="$(TZ=America/New_York date "+%A, %B %d, %Y @ %l:%M %p ET" | sed 's/  / /g')"
-git commit -F "extras/commit_messages/<filename>.md" --trailer "commit generated at ${LONG_DTTM}"
+git commit -F "tmp/commit_messages/<filename>.md" --trailer "commit generated at ${LONG_DTTM}"
 ```
 
 ---
diff --git a/commands/self-review.md b/commands/self-review.md
@@ -164,7 +164,7 @@ Generate a structured review report:
 
 **Generate Audit Report (per `020-agent-audit.mdc`):**
 
-- Ensure `GIT_REPO_ROOT` is set, then write/append the report to `<GIT_REPO_ROOT>/extras/agent_reports/$(date +%F)-agent-report-<repo>-<branch>.md` (if `<GIT_REPO_ROOT>/extras/` exists and is gitignored) or `/tmp/$(date +%F)-agent-report-<repo>-<branch>.md`
+- Ensure `GIT_REPO_ROOT` is set, then write/append the report to `<GIT_REPO_ROOT>/tmp/agent_reports/$(date +%F)-agent-report-<repo>-<branch>.md` (if `<GIT_REPO_ROOT>/tmp/` exists and is gitignored) or `/tmp/$(date +%F)-agent-report-<repo>-<branch>.md`
 - Include:
   - Start/end timestamps (local and UTC)
   - Repo name, branch name, `HEAD` SHA
diff --git a/docs/HOW-TO-USE.md b/docs/HOW-TO-USE.md
@@ -85,7 +85,7 @@ rules:
 | Personal setup, all projects | Symlink to `~/.cursor/rules/` (Approach A) |
 | Team project, shared config | `.cursorrules` in git (Approach B) |
 | Project-specific subset | `.cursorrules` with explicit list (Approach B) |
-| Mixed (global + project) | Both: symlink globals + `.cursorrules` for extras |
+| Mixed (global + project) | Both: symlink globals + `.cursorrules` for project-specific additions |
 
 ---
 
diff --git a/rules/010-workflow.mdc b/rules/010-workflow.mdc
@@ -86,13 +86,13 @@ You MUST follow this three-phase approach for all non-trivial changes:
 
 For non-trivial work, keep a single “north star” scope document and use it to drive small, sequential feature slices.
 
-- **Recommended file**: `extras/prd.md`
-- **Design doc (recommended when architecture/approach matters)**: `extras/design.md`
+- **Recommended file**: `tmp/prd.md`
+- **Design doc (recommended when architecture/approach matters)**: `tmp/design.md`
 - **Greenfield**: Define scope, non-goals, key flows, architecture, milestones
 - **Brownfield**: Capture current state + next desired state + constraints
 - **Rule**: Break work into features small enough for the agent to execute reliably (one feature per cycle)
 
-**When to create `extras/design.md`:**
+**When to create `tmp/design.md`:**
 - Level 3–4 tasks (multi-module or architectural)
 - Any time there are multiple valid approaches with meaningful tradeoffs
 - Any time interfaces, data models, or operational behaviors might change
@@ -108,7 +108,7 @@ For non-trivial work, keep a single “north star” scope document and use it t
 1. **Analyze the request** - Understand scope, constraints, and requirements
 2. **Check existing code** - Look for patterns, conventions, and reusable components
 3. **Design the solution** - Propose approach with alternatives considered
-4. **Create/update context files** - Document plan in `tasks.md` or `active-context.md` (in `extras/` directory)
+4. **Create/update context files** - Document plan in `tasks.md` or `active-context.md` (in `tmp/` directory)
 5. **WAIT FOR APPROVAL** - Present plan and await explicit confirmation before proceeding
 
 **Output:**
@@ -236,7 +236,7 @@ Treat recurring mistakes as a signal to improve the system, not just the code:
 
 - **If a bug recurs**: update the relevant rule(s), command(s), or reference docs so it doesn’t happen again
 - **If validation was missed**: update templates/commands to force the check (tests, lint, security scan)
-- **Capture learnings**: record patterns in `extras/reflect-*.md` (Level 3-4) and keep the guidance crisp
+- **Capture learnings**: record patterns in `tmp/reflect-*.md` (Level 3-4) and keep the guidance crisp
 
 **Review Checklist:**
 - [ ] Changes match the agreed plan
@@ -257,41 +257,41 @@ Treat recurring mistakes as a signal to improve the system, not just the code:
 
 ##  Context File Management
 
-**IMPORTANT**: Context files are **workspace-specific** and should be in the **extras/** directory in the project root, NOT in the rules directory. This allows each workspace to have its own context while sharing rules via symlinks.
+**IMPORTANT**: Context files are **workspace-specific** and should be in the **tmp/** directory in the project root, NOT in the rules directory. This allows each workspace to have its own context while sharing rules via symlinks.
 
 > [!IMPORTANT]
-> `extras/` is intended for **workspace-local context and artifacts** and should be **gitignored by default**.
+> `tmp/` is intended for **workspace-local context and artifacts** and should be **gitignored by default**.
 >
-> Do **not** commit or push files under `extras/` unless the user explicitly requests it (for example, promoting a draft document from `extras/` into the repo proper).
+> Do **not** commit or push files under `tmp/` unless the user explicitly requests it (for example, promoting a draft document from `tmp/` into the repo proper).
 
 > [!NOTE]
 > For prompt packing, retrieval, and “frequent intentional compaction” patterns, see `015-context-engineering.mdc`.
 
-**Templates:** Copy/paste-ready templates live alongside these rules under `templates/` (e.g., `.cursor/rules/templates/` when installed). In this repo, that path is `rules/templates/`. Copy them into `extras/` when you start a new workspace.
+**Templates:** Copy/paste-ready templates live alongside these rules under `templates/` (e.g., `.cursor/rules/templates/` when installed). In this repo, that path is `rules/templates/`. Copy them into `tmp/` when you start a new workspace.
 
-For complex projects, maintain context files in the `extras/` directory:
+For complex projects, maintain context files in the `tmp/` directory:
 
 ### `project-brief.md` - Project Overview (Optional, Recommended)
 Use this when starting work in a new repo/workspace (or when context resets) so the agent has stable, high-level grounding.
 - **Template:** `templates/project-brief.md.template`
-- **Workspace file:** `extras/project-brief.md`
+- **Workspace file:** `tmp/project-brief.md`
 
 ### `tasks.md` - Source of Truth
 - **Template:** `templates/tasks.md.template`
-- **Workspace file:** `extras/tasks.md`
+- **Workspace file:** `tmp/tasks.md`
 
 ### `active-context.md` - Current Focus
 - **Template:** `templates/active-context.md.template`
-- **Workspace file:** `extras/active-context.md`
+- **Workspace file:** `tmp/active-context.md`
 
 ### `progress.md` - Implementation Status
 - **Template:** `templates/progress.md.template`
-- **Workspace file:** `extras/progress.md`
+- **Workspace file:** `tmp/progress.md`
 
 ### `reflect-*.md` - Review Documents
 Create one per significant task:
 - **Template:** `templates/reflect-template.md.template`
-- **Workspace file:** `extras/reflect-<task>.md`
+- **Workspace file:** `tmp/reflect-<task>.md`
 
 ---
 
@@ -394,7 +394,7 @@ Implementation CANNOT proceed until all creative phases are completed.
 
 **Template:**
 - **Template:** `templates/creative-template.md.template`
-- **Workspace file:** `extras/creative-<component-or-feature>.md`
+- **Workspace file:** `tmp/creative-<component-or-feature>.md`
 
 ---
 
diff --git a/rules/015-context-engineering.mdc b/rules/015-context-engineering.mdc
@@ -26,7 +26,7 @@ This rule strengthens agent performance by making context **intentional**, **min
 
 - **Working context (volatile)**: what the model sees right now
 - **Repo context (retrievable)**: files, diffs, logs, docs that can be re-read on demand
-- **Durable context (portable)**: short summaries + decisions captured in `extras/` context files
+- **Durable context (portable)**: short summaries + decisions captured in `tmp/` context files
 
 > [!IMPORTANT]
 > If it’s important and will matter later, it must be captured in **durable context**.
@@ -69,12 +69,12 @@ Use a tight loop:
 
 After any meaningful milestone (plan approved, a module completed, a bug fixed), compact:
 
-- Update `extras/active-context.md` with:
+- Update `tmp/active-context.md` with:
   - **Current focus**
   - **Key decisions** (what and why)
   - **Blockers** (and next action)
   - **Context from previous sessions** (only what must persist)
-- Update `extras/progress.md` (if used) with “done/next”
+- Update `tmp/progress.md` (if used) with “done/next”
 - Add a **Handoff Bundle** (copy/pasteable) for resuming work
 
 ### Handoff Bundle (copy/paste)
@@ -101,7 +101,7 @@ Prefer a fresh chat/session when:
 
 When restarting, bring only:
 
-- The approved plan (or the updated `extras/tasks.md`)
+- The approved plan (or the updated `tmp/tasks.md`)
 - The Handoff Bundle
 - The minimal file/line references needed to continue
 
diff --git a/rules/020-agent-audit.mdc b/rules/020-agent-audit.mdc
@@ -132,8 +132,8 @@ Agents MUST resolve the absolute repository root path:
 - `export GIT_REPO_ROOT="$(git rev-parse --show-toplevel)"`
 
 ### Path rules
-- If `<GIT_REPO_ROOT>/extras/` exists **and** it is gitignored, write to:
-  - `<GIT_REPO_ROOT>/extras/agent_reports/$(date +%F)-agent-report-<repo>-<branch>.md`
+- If `<GIT_REPO_ROOT>/tmp/` exists **and** it is gitignored, write to:
+  - `<GIT_REPO_ROOT>/tmp/agent_reports/$(date +%F)-agent-report-<repo>-<branch>.md`
 - Otherwise write to:
   - `/tmp/$(date +%F)-agent-report-<repo>-<branch>.md`
 
@@ -166,13 +166,13 @@ For complex debugging sessions or demos, agents MAY create terminal recordings u
 - When user explicitly requests a recording
 
 **Recording path:**
-- Save to: `<GIT_REPO_ROOT>/extras/agent_reports/recordings/$(date +%F)-agent-recording-<repo>-<branch>-$(date +%H%M%S).cast`
+- Save to: `<GIT_REPO_ROOT>/tmp/agent_reports/recordings/$(date +%F)-agent-recording-<repo>-<branch>-$(date +%H%M%S).cast`
 - Reference the recording path in the markdown audit report
 
 **How to record:**
 ```bash
 # Start recording
-asciinema rec -q "<GIT_REPO_ROOT>/extras/agent_reports/recordings/session.cast"
+asciinema rec -q "<GIT_REPO_ROOT>/tmp/agent_reports/recordings/session.cast"
 
 # ... perform commands ...
 
diff --git a/rules/120-utilities.mdc b/rules/120-utilities.mdc
@@ -103,7 +103,7 @@ Guidance for diagram prompting:
 
 Artifact handling (screenshots):
 
-- In a git repo: save screenshots under a gitignored folder (commonly `extras/` or `tmp/`) and include the local path in your response.
+- In a git repo: save screenshots under a gitignored folder (commonly `tmp/`) and include the local path in your response.
 - Outside a git repo: save to `$TMPDIR` (macOS) or `/tmp`.
 - Use descriptive filenames (include site + page/section + timestamp) so artifacts can be re-opened.
 - Never commit binary artifacts unless the user explicitly asks.
diff --git a/rules/templates/design.md.template b/rules/templates/design.md.template
@@ -4,7 +4,7 @@
 [One paragraph summary of the approach.]
 
 ## Context
-- **Link to PRD**: `extras/prd.md`
+- **Link to PRD**: `tmp/prd.md`
 - **Current state**: [what exists today]
 - **Desired state**: [what will exist after]
 
diff --git a/setup-workspace.sh b/setup-workspace.sh
diff --git a/skills/agent-workflow/references/audit-requirements.md b/skills/agent-workflow/references/audit-requirements.md
diff --git a/skills/agent-workflow/references/context-engineering.md b/skills/agent-workflow/references/context-engineering.md
diff --git a/skills/agent-workflow/references/context-management.md b/skills/agent-workflow/references/context-management.md
diff --git a/skills/agent-workflow/references/context-templates.md b/skills/agent-workflow/references/context-templates.md
diff --git a/skills/agent-workflow/references/design-template.md b/skills/agent-workflow/references/design-template.md
diff --git a/skills/agent-workflow/references/workflow-commands.md b/skills/agent-workflow/references/workflow-commands.md
