tunacode-cli 0.0.72__tar.gz → 0.0.75__tar.gz

tunacode_cli-0.0.75/.claude/commands/context-engineer/QA.md

@@ -0,0 +1,106 @@
+---
+allowed-tools: View, Bash(git:*), Bash(grep:*), Bash(jq:*), Bash(python:*), Bash(pytest:*), Bash(coverage:*), Bash(mypy:*), Bash(trivy:*), Bash(hadolint:*), Bash(dive:*), Bash(npm:*), Bash(lighthouse:*), Bash(kubectl:*), Bash(helm:*), Bash(curl:*), Bash(gh:*)
+description: READ-ONLY QA focused FIRST on code-logic correctness of recent changes. Outlines issues/smells/antipatterns and risks. NO CODING, NO EDITS, NO FIXES.
+writes-to: memory-bank/QA/
+hard-guards:
+  - Do not modify source files
+  - Do not create commits/branches/PRs
+  - Do not run formatters/linters in write mode
+  - Produce findings & recommendations ONLY (outline, not code)
+---
+
+# QA (Read-Only) — Code Logic First
+
+Run a post-execution QA review for: $ARGUMENTS  (topic OR path to plan/report)
+
+## Initial Prompt (to user)
+"I'm starting a **read-only** QA review focused on the **code logic of recent changes**. I will outline potential logic issues, smells/anti-patterns, and security concerns. **No coding or fixes will be performed.** Please provide a topic or the path to the plan/report under memory-bank/execute/."
+
+## Strict Ordering
+1) Locate artifacts → 2) Build change set (commit range & diff) → 3) Code-logic review (primary) → 4) Tests & contracts review → 5) Secondary scans (optional, read-only) → 6) Synthesize findings → 7) Save QA report
+
+## Step 1 — Locate Inputs
+- Resolve target by $ARGUMENTS:
+  - If path given: use it.
+  - If topic: select newest matching under `memory-bank/plan/` and `memory-bank/execute/`.
+- Read FULLY (no offsets):
+  - Plan: `memory-bank/plan/...`
+  - Execution Log: `memory-bank/execute/*_log.md` (if exists)
+  - Execution Report: `memory-bank/execute/*_report.md` (if exists)
+
+## Step 2 — Build the Change Set (read-only)
+- Determine commit range:
+  - Start: from plan/log (`start_commit`) if available; else last tagged release or previous commit.
+  - End: current HEAD (or end_commit in report).
+- Capture diffs:
+  - !`git diff --name-status <start>..<end>`
+  - !`git diff --stat <start>..<end>`
+  - !`git log --oneline <start>..<end>`
+- Extract changed files (focus on src/ and tests/), group by module/package.
+- For each changed file:
+  - !`git diff <start>..<end> -- <file>` (context for evidence referencing only)
+
+## Step 3 — Code-Logic Review (PRIMARY)
+Evaluate only the changed areas, emphasizing control/data flow correctness.
+
+Checklist (apply per module/file/function changed):
+- **Inputs & Preconditions**: validation, type assumptions, null/empty, boundary values.
+- **Control Flow**: branching completeness, unreachable paths, fall-through, early returns.
+- **Data Flow**: invariant preservation, mutation scope, shared state leakage, aliasing risks.
+- **State & Transactions**: idempotency, atomicity, rollback behavior, race/concurrency hazards.
+- **Error Handling**: specific exceptions vs broad catches, retry/backoff, dead-letter paths.
+- **Contracts**: pre/post-conditions, schema compatibility (request/response, DTOs), versioning.
+- **Time/Locale**: timezones, monotonic clocks, DST, parsing/formatting stability.
+- **Resource Hygiene**: file/conn lifecycle, timeouts, cancellation propagation.
+- **Edge Cases**: empty sets, max sizes, pagination, partial failure scenarios.
+- **Public Surface**: backward compatibility, OpenAPI/types alignment.
+
+## Step 4 — Tests & Contracts (READ-ONLY)
+- Map **each changed public function/endpoint** to test coverage:
+  - !`pytest -q` (read result), !`coverage run -m pytest && coverage report --format=markdown`
+  - Identify **missing cases**: error branches, boundary conditions, property invariants, mutation tests.
+- Contract/API checks (if applicable):
+  - OpenAPI/JSON schema drift vs implementations.
+  - Client compatibility (breaking field/enum changes).
+
+## Step 5 — Secondary Scans (Optional, Read-Only)
+- Static/security summaries (no write/auto-fix):
+  - `mypy` (report only), `bandit -r . -q || true`, `pip-audit` / `npm audit --json | jq`.
+- Container & deploy context (if relevant): `hadolint`, `trivy`, `dive` summaries.
+- Web (if staged): brief Lighthouse JSON summary for **regressions** only.
+
+## Step 6 — Write QA Report
+Create `memory-bank/QA/YYYY-MM-DD_HH-MM-SS_<topic>_qa.md` with:
+
+---
+title: "<topic> – QA Report (Code Logic First)"
+phase: QA
+date: "{{timestamp}}"
+owner: "{{agent_or_user}}"
+sources:
+  plan: "memory-bank/plan/<file>.md"
+  execution_log: "memory-bank/execute/<logfile>.md"
+  execution_report: "memory-bank/execute/<reportfile>.md"
+  commit_range: "<start>..<end>"
+policy: "READ-ONLY QA — NO CODING OR CHANGES"
+scope: "Changed code only (logic-first), plus impacted contracts/tests"
+---
+
+## 0. Summary Verdict
+- Overall: ✅ Accept | ⚠️ Accept w/ Conditions | ❌ Reject
+- Top logic risks (3–5 bullets)
+- Required follow-ups (non-prescriptive)
+
+## 1. Change Summary (What changed)
+- Commit range: <start>..<end>
+- Diffstat: <files/insertions/deletions>
+- Modules touched:
+  - `<pkg/module>` — files changed: n (list)
+- User-visible behavior changes (from plan/report): bullets
+
+## 2. Code-Logic Findings (by severity)
+> Each item includes **Evidence (file:lines, commit)**, **Impact**, **Likelihood**, **Suggested Remediation (outline only)**, **Owner**, **Due-by**.
+
+### Critical
+- [CR-1] <title> — Evidence: `<file>#Lx-Ly` (commit `<sha>`), Impact: …, Likelihood: …
+### High

tunacode_cli-0.0.75/.claude/commands/context-engineer/documentation-synthesis.md

@@ -0,0 +1,114 @@
+---
+allowed-tools: View, Bash(git:*), Bash(jq:*), Bash(curl:*), Bash(gh:*), Bash(python:*), Bash(npm:*), Bash(kubectl:*), Bash(helm:*)
+description: Synthesizes final documentation from Research → Plan → Execute → QA. Produces a clean developer-facing doc with context, decisions, and next steps.
+writes-to: memory-bank/documentation
+hard-guards:
+  - Do not modify or rewrite research/plan/execute/QA artifacts
+  - Produce a new synthesis doc only
+  - No coding, fixes, or commits
+---
+
+# Documentation Synthesis (Final)
+
+Create synthesized documentation for: $ARGUMENTS
+(topic OR path to QA report)
+
+## Initial Prompt
+"I'm creating a **final documentation synthesis** that integrates Research, Plan, Execution, and QA. This is meant to prep the next developer to continue the work smoothly."
+
+---
+
+## Step 1 — Locate Inputs
+- If `$ARGUMENTS` is a topic: find the newest chain in memory-bank (`research/`, `plan/`, `execute/`, `QA/`).
+- If `$ARGUMENTS` is a path to QA report: trace its linked plan, log, report, and research.
+- Always read FULLY (no offsets):
+  - Research doc
+  - Plan doc
+  - Execution Log
+  - Execution Report
+  - QA Report
+
+---
+
+## Step 2 — Extract Metadata
+- Topic, dates, owners from each doc.
+- Commit ranges (from plan + execute).
+- Verdict (from QA).
+- Key tags, milestones, decisions.
+
+---
+
+## Step 3 — Write Synthesis Doc
+Create `memory-bank/documentation/YYYY-MM-DD_HH-MM-SS_<topic>_synthesis.md`:
+
+```markdown
+---
+title: "<topic> – Documentation Synthesis"
+phase: Documentation
+date: "{{timestamp}}"
+owner: "{{agent_or_user}}"
+sources:
+  research: "memory-bank/research/<file>.md"
+  plan: "memory-bank/plan/<file>.md"
+  execute_log: "memory-bank/execute/<log>.md"
+  execute_report: "memory-bank/execute/<report>.md"
+  qa: "memory-bank/QA/<file>.md"
+commit_range: "<start>..<end>"
+verdict: "<QA verdict>"
+---
+
+# Documentation Synthesis – <topic>
+
+## 0. Executive Summary
+- One-paragraph overview of what was done and why
+- QA verdict + top risks
+- Next action for future dev
+
+## 1. Context & Research
+- Problem statement (from research)
+- Key findings & gaps identified
+- Linked references (permalinks, docs)
+
+## 2. Plan Highlights
+- Scope & assumptions
+- Major milestones
+- Deliverables & acceptance criteria
+- Risks & mitigations
+
+## 3. Execution Summary
+- Commit range: `<start>..<end>`
+- Work done by milestone
+- Key tests, builds, deployments
+- Deviations from plan (if any)
+- Success criteria achieved vs missed
+
+## 4. QA Findings
+- Overall verdict: ✅ / ⚠️ / ❌
+- Critical/high issues summary
+- Smells & anti-patterns observed
+- Ship conditions (if ⚠️)
+
+## 5. Lessons Learned
+- What worked well
+- What caused friction
+- Reusable patterns / gotchas
+
+## 6. Next Steps for Developers
+- Open follow-ups / tech debt
+- Areas needing re-review
+- Suggested tasks for next cycle
+- Monitoring/observability items to watch
+
+## 7. References
+- Direct links to all artifacts
+- GitHub permalinks (commits, files)
+- Tickets/Issues
+
+
+DEPLOY 3 paralel SUBAGENTS at most or one IF needed you can also you 1 or 2 use you best judgment
+
+- codebase-analyzer to outline your code changes in relation to the codebase
+
+- antipattern-sniffer any new code MUST be evaluted by this subagent
+
+- context-synthesis a agent to gather context as needed

tunacode_cli-0.0.75/.claude/commands/context-engineer/execute.md

@@ -0,0 +1,176 @@
+---
+allowed-tools: Edit, View, Bash(git:*), Bash(python:*), Bash(pytest:*), Bash(mypy:*), Bash(black:*), Bash(coverage:*), Bash(mutmut:*), Bash(docker:*), Bash(trivy:*), Bash(hadolint:*), Bash(dive:*), Bash(npm:*), Bash(kubectl:*), Bash(helm:*), Bash(lighthouse:*), Bash(jq:*), Bash(curl:*), Bash(gh:*)
+description: Executes a plan with gated checks, atomic commits, build/package/deploy, full validation, and immutable execution logs
+writes-to: memory-bank/execute/
+---
+
+# Execute Plan
+
+Execute the implementation according to: $ARGUMENTS  (path to a Plan doc)
+
+## Initial Setup (prompt)
+"I'm ready to execute. Please provide the path to the Plan document in memory-bank/plan/."
+
+
+
+## Strict Ordering
+1) Read plan FULLY → 2) Pre-flight checks → 3) Implement by tasks → 4) Validate gates → 5) Package/Deploy → 6) Post-deploy verification → 7) Persist log
+
+## Step 1 — Read Plan & Lock Context
+- Read FULL `memory-bank/plan/<file>.md`.
+- Extract: milestones, tasks (IDs), acceptance tests, gates, rollout, success metrics.
+
+## Step 2 — Pre-Flight Snapshot
+Record into execution log header:
+- Active branch: !`git branch --show-current`
+- ROLL BACK POINT: YOU MUST CREATE A GIT COMIMT WITH A ROLLBACK POINT.
+
+Create `memory-bank/execute/YYYY-MM-DD_HH-MM-SS_<topic>.md`:
+
+You MUST keep this SINGULAR documen in synch as you work
+
+DO NOT MAKE MULTIPLE DOCUMENT WILL BE YOUR LOG FOR THE EXCUTION
+
+---
+title: "<topic> – Execution Log"
+phase: Execute
+date: "{{timestamp}}"
+owner: "{{agent_or_user}}"
+plan_path: "memory-bank/plan/<file>.md"
+start_commit: "<short_sha>"
+env: {target: "local|staging|prod", notes: ""}
+---
+
+## Pre-Flight Checks
+- DoR satisfied?
+- Access/secrets present?
+- Fixtures/data ready?
+- If any **NO** → abort and append **Blockers** section.
+
+## Step 3 — Task-By-Task Implementation (Atomic)
+For each Task (in plan order):
+1. Create/confirm rollback
+2. Implement minimal slice aligned with acceptance tests
+3. Run local quality bar
+4. Commit atomic change with Task ID in message
+5. Update **Execution Log** with:
+   - Files touched, commands, outputs (trimmed), coverage deltas, notes
+
+## Step 4 — Quality Gates (Enforced)
+- Gate C (Pre-merge):
+  - Tests pass
+  - Coverage ≥ plan threshold (e.g., 90%+ new/changed lines)
+  - Type checks clean
+  - Linters OK
+
+- If any gate FAILS → record failure + remediation then dont roll back just stop and ask the user for next steps
+
+
+
+## Step 5 — Permalinks & Artifacts
+- If commits pushed:
+  - !`gh repo view --json owner,name`
+  - Attach permalinks to PRs/commits and to artifacts (build logs, coverage HTML)
+- Persist artifact pointers in **Execution Log**.
+
+## Execution Log Template (append as you go)
+### Task <ID> – <Summary>
+- Commit: `<short_sha>`
+- Commands:
+  - `<cmd>` → `<trimmed output>`
+- Tests/coverage:
+  - `<result>`
+- Notes/decisions:
+  - `<why>`
+
+### Gate Results
+- Gate C: pass/fail + evidence
+- Security: pass/fail + evidence
+- Perf/PWA (if applicable): metrics
+
+### Deployment Notes
+- Staging → Prod timestamps
+- Smoke/E2E results
+- SLO/SLA snapshot
+
+### Post-Deploy Verification
+- Error rates, latencies, dashboards screenshots/links
+- On-call runbook links
+
+### Follow-ups
+- TODOs, tech debt, docs to update
+
+## Success Criteria (auto-check)
+- All planned gates passed
+- Rollout completed or rollback clean
+- KPIs/SLOs within thresholds
+- Execution log saved to `memory-bank/execute/` and linked back to Plan
+
+# Execution Report – <topic>
+
+**Date:** {{date}}
+**Plan Source:** <plan file>
+**Execution Log:** <log file>
+
+## Overview
+- Environment: local|staging|prod
+- Start commit: <sha>
+- End commit: <sha>
+- Duration: Xh Ym
+- Branch: <branch>
+- Release: <tag|helm release>
+
+## Outcomes
+- Tasks attempted: N
+- Tasks completed: N
+- Rollbacks: Y/N
+- Final status: ✅ Success | ❌ Failure
+
+## Gate Results
+- Tests: pass/fail summary
+- Coverage: X% (target Y%)
+- Type checks: pass/fail
+- Security scans: # issues
+- Perf/PWA scores: numbers
+
+## Issues & Resolutions
+- <task ID> – <issue> → <fix>
+- <task ID> – <issue> → <rollback>
+
+## Deployment Notes
+- Staging deploy: success/fail
+- Prod deploy: success/fail
+- Smoke/E2E results
+- Observability checks
+
+## Success Criteria
+- Which criteria met vs missed
+
+## Next Steps
+- Follow-ups, tech debt, docs to update
+
+## References
+- Plan doc
+- Execution log
+- GitHub permalinks
+
+
+CLEARLY SUMMARIZE WHA YOU DID AND TOUCHED
+
+YOU ARE CODING AS YOU UPDATE THIS DOCUMENT
+
+SAVE THE DOCUMENT YOU MUST SAVE IN THE CORRECT FORMAT FOR THE NEXT DEV
+
+ALWAYS FOLLOW BEST PRACTISES
+
+THIS IS THE MOST IMPORTANT PART OF THIS PROMPT:MAKE THE DOCUMENT AND UPDATE AS YOU WORK.
+
+AFTER THE WORK IS DONE
+
+DEPLOY 3 SUBAGENTS at most
+
+- codebase-analyzer to outline your code changes in relation to the codebase
+
+- antipattern-sniffer any new code MUST be evaluted by this subagent
+
+- context-synthesis a agent to gather context as needed

tunacode_cli-0.0.75/.claude/commands/context-engineer/plan.md

@@ -0,0 +1,112 @@
+---
+allowed-tools: Edit, View, Bash(git:*), Bash(python:*), Bash(pytest:*), Bash(mypy:*), Bash(black:*), Bash(npm:*), Bash(jq:*)
+description: Generates a concrete implementation plan from a research doc, with milestones, tasks, gates, risks, DoD/DoR, and acceptance tests
+writes-to: memory-bank/plan/
+---
+
+# Plan From Research
+
+Create an execution-ready implementation plan for: $ARGUMENTS
+
+## Initial Setup (prompt)
+"I'm ready to plan the work. Please provide either the path to the research document in memory-bank/research/ or a short topic to find it."
+
+## Strict Ordering
+1) Read research doc FULLY → 2) Validate freshness → 3) Plan milestones/tasks → 4) Define gates/criteria → 5) Persist plan
+
+## Step 1 — Input & Context
+- If path provided: Read FULL file (no offsets) from `memory-bank/research/`.
+- If topic provided: grep/select the latest `memory-bank/research/*topic*.md` and read FULLY.
+- Extract: scope, constraints, key files, unresolved questions, suggested solutions, references.
+
+## Step 2 — Freshness & Diff Check
+- Capture current git state:
+  - !`git rev-parse --short HEAD`
+  - !`git status --porcelain`
+- If code changed since research doc commit:
+  - Append **"Drift Detected"** note and mark items requiring re-verification.
+
+## Step 3 — Planning Decomposition
+Create `memory-bank/plan/YYYY-MM-DD_HH-MM-SS_<topic>.md` with this exact structure:
+
+---
+title: "<topic> – Plan"
+phase: Plan
+date: "{{timestamp}}"
+owner: "{{agent_or_user}}"
+parent_research: "memory-bank/research/<file>.md"
+git_commit_at_plan: "<short_sha>"
+tags: [plan, <topic>]
+---
+
+## Goal
+- Crisp statement of outcomes and non-goals.
+- MOST IMPORTANT SETANCE IN THIS PROMPT: WE MUST CLARIFY THE SINGULAR GOAL AND FOCUS ON EXCUTION.
+
+## Scope & Assumptions
+- In / Out of scope
+- Explicit assumptions & constraints
+
+## Deliverables (DoD)
+- Artifacts with measurable acceptance criteria (tests, docs, endpoints, CLIs, dashboards).
+
+## Readiness (DoR)
+- Preconditions, data, access, envs, fixtures required to start.
+
+## Milestones
+- M1: Architecture & skeleton
+- M2: Core feature(s)
+- M3: Tests & hardening
+- M4: Packaging & deploy
+- M5: Observability & docs
+
+## Work Breakdown (Tasks)
+- Task ID, summary, owner, estimate, dependencies, target milestone
+- For each task: **Acceptance Tests** (bullet list), **Files/Interfaces** touched
+
+## Risks & Mitigations
+- Risk → Impact → Likelihood → Mitigation → Trigger
+
+## Test Strategy
+- Unit/Property/Mutation
+- Integration/Contract
+- E2E/Smoke/Perf (thresholds)
+
+## Security & Compliance
+- Secret handling, authZ/authN, threat model notes, scans to run
+
+## Observability
+- Metrics, logs, traces to emit; dashboards to add/modify
+
+## Rollout Plan
+- Env order, migration steps, feature flags, rollback triggers
+
+## Validation Gates
+- Gate A (Design sign-off)
+- Gate B (Test plan sign-off)
+- Gate C (Pre-merge quality bar)
+- Gate D (Pre-deploy checks)
+
+## Success Metrics
+- KPIs / SLOs, error budgets, perf ceilings
+
+## References
+- Research doc sections, GitHub permalinks, tickets
+
+## Agents
+
+- you can deploy maxium TWO subagents
+- context-synthesis subagent
+- codebase-analyzer subagent
+
+## Final Gate
+- Output a short summary with: plan path, milestones count, gates, and next command hint: `/execute "<plan_path>"`
+
+- this mustbe be a singualr focused plan, we cna have ONE other option in the same document but in general we MUST have a singular focused plan on execution.
+
+
+  DO NOT CODE YOU WILL BE PUNISHED FOR CODING
+
+  SAVE THE DOCUMENT YOU MUST SAVE IN THE CORRECT FORMAT FOR THE NEXT DEV
+
+  ALWAYS FOLLOW BEST PRACTISES

tunacode_cli-0.0.75/.claude/commands/context-engineer/research.md

@@ -0,0 +1,148 @@
+# Research Codebase
+
+You are tasked with conducting comprehensive research across the codebase to answer user questions by spawning parallel sub-agents and synthesizing their findings. All research documents must be stored in the `memory-bank/research/` directory, following the YAML frontmatter and content structure below.
+
+## Initial Setup:
+
+When this command is invoked, respond with:
+```
+I'm ready to research the codebase. Please provide your research question or area of interest, and I'll analyze it thoroughly by exploring relevant components and connections.
+```
+
+Then wait for the user's research query.
+
+## Steps to follow after receiving the research query:
+
+1. **Read any directly mentioned files first:**
+   - If the user mentions specific files (tickets, docs, JSON), read them FULLY first
+   - **IMPORTANT**: Use the Read tool WITHOUT limit/offset parameters to read entire files
+   - **CRITICAL**: Read these files yourself in the main context before spawning any sub-tasks
+   - This ensures you have full context before decomposing the research
+
+2. **Analyze and decompose the research question:**
+   - Break down the user's query into composable research areas
+   - Take time to ultrathink about the underlying patterns, connections, and architectural implications the user might be seeking
+   - Identify specific components, patterns, or concepts to investigate
+   - Create a research plan using TodoWrite to track all subtasks
+   - Consider which directories, files, or architectural patterns are relevant
+
+3. **Spawn parallel sub-agent tasks for comprehensive research:**
+   - Strictly limit to a maximum of 3 Task agents per research query. You may not spawn more than two sub-agents for any research query, regardless of the number of aspects or subtasks. This is a hard limit.
+   - Only reference files and resources that are part of the current codebase or workspace. Do not reference or include any files, tickets, or resources that are external or not present in this workspace.
+
+
+   YOU MUST DEPLOY THESE 3 IN PARELLEL
+   YOU WILL BE PUNISHED FOR NOT DEPLOYING SUBAGENT
+
+   **For codebase research:**
+   - Use the **codebase-locator** agent to find WHERE files and components live
+   - Use the **codebase-analyzer** agent to understand HOW specific code works
+   - Use the **context-synthesis** agent to find context as needed
+
+   The key is to use these agents intelligently:
+   - Start with locator agents to find what exists
+   - Then use analyzer agents on the most promising findings
+   - Run agents in parallel only if they are searching for different things, and never exceed two concurrent sub-agents.
+   - Each agent knows its job - just tell it what you're looking for
+   - Don't write detailed prompts about HOW to search - the agents already know
+
+4. **Wait for all sub-agents to complete and synthesize findings:**
+   - IMPORTANT: Wait for ALL sub-agent tasks to complete before proceeding
+   - Compile all sub-agent results (both codebase and thoughts findings)
+   - Prioritize live codebase findings as primary source of truth
+   - Use thoughts/ findings as supplementary historical context
+   - Connect findings across different components
+   - Include specific file paths and line numbers for reference
+   - Verify all thoughts/ paths are correct (e.g., thoughts/allison/ not thoughts/shared/ for personal files)
+   - Highlight patterns, connections, and architectural decisions
+   - Answer the user's specific questions with concrete evidence
+
+5. **Gather metadata for the research document:**
+   - Filename: `memory-bank/research/YYYY-MM-DD_HH-MM-SS_topic.md`
+
+6. **Generate research document:**
+      - Use the metadata gathered in step 4
+      - Structure the document in the following format and store in `memory-bank/research/`:
+         ```markdown
+         # Research – <TASK_NAME>
+         **Date:** {{date}}
+         **Owner:** {{agent or user}}
+         **Phase:** Research
+
+         ## Goal
+         Summarize all *existing knowledge* before any new work.
+
+
+         - Additional Search:
+            - `grep -ri "<term>" .claude/`
+
+         ## Findings
+         - Relevant files & why they matter:
+            - `<file>` → `<reason>`
+            - `<file>` → `<reason>`
+
+         ## Key Patterns / Solutions Found
+         - `<pattern>`: short description, relevance
+
+         ## Knowledge Gaps
+         - Missing context or details for next phase
+
+         ## References
+         - Links or filenames for full review
+         ```
+
+7. **Add GitHub permalinks (if applicable):**
+    - Check if on main branch or if commit is pushed: `git branch --show-current` and `git status`
+    - If on main/master or pushed, generate GitHub permalinks:
+       - Get repo info: `gh repo view --json owner,name`
+       - Create permalinks: `https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line}`
+    - Replace local file references with permalinks in the document
+    - For research documents, update references to use `memory-bank/research/` paths where applicable.
+
+
+
+9. **Handle follow-up questions:**
+   - If the user has follow-up questions, append to the same research document
+   - Update the frontmatter fields `last_updated` and `last_updated_by` to reflect the update
+   - Add `last_updated_note: "Added follow-up research for [brief description]"` to frontmatter
+   - Add a new section: `## Follow-up Research [timestamp]`
+   - Spawn new sub-agents as needed for additional investigation
+   - Continue updating the document and syncing
+
+## Important notes:
+- Always use parallel Task agents to maximize efficiency and minimize context usage
+- Always run fresh codebase research - never rely solely on existing research documents
+- The thoughts/ directory provides historical context to supplement live findings
+- Focus on finding concrete file paths and line numbers for developer reference
+- Research documents should be self-contained with all necessary context
+- Each sub-agent prompt should be specific and focused on read-only operations
+- Consider cross-component connections and architectural patterns
+- Include temporal context (when the research was conducted)
+- Link to GitHub when possible for permanent references
+- Keep the main agent focused on synthesis, not deep file reading
+- Encourage sub-agents to find examples and usage patterns, not just definitions
+- Explore all of thoughts/ directory, not just research subdirectory
+- **File reading**: Always read mentioned files FULLY (no limit/offset) before spawning sub-tasks
+- **Critical ordering**: Follow the numbered steps exactly
+  - ALWAYS read mentioned files first before spawning sub-tasks (step 1)
+  - ALWAYS wait for all sub-agents to complete before synthesizing (step 4)
+  - ALWAYS gather metadata before writing the document (step 5 before step 6)
+  - NEVER write the research document with placeholder values
+- **Path handling**: The thoughts/searchable/ directory contains hard links for searching
+  - Always document paths by removing ONLY "searchable/" - preserve all other subdirectories
+
+  - NEVER change allison/ to shared/ or vice versa - preserve the exact directory structure
+  - This ensures paths are correct for editing and navigation
+- **Frontmatter consistency**:
+  - Always include frontmatter at the beginning of research documents
+  - Keep frontmatter fields consistent across all research documents
+  - Update frontmatter when adding follow-up research
+  - Use snake_case for multi-word field names (e.g., `last_updated`, `git_commit`)
+  - Tags should be relevant to the research topic and components studied
+
+
+  DO NOT CODE YOU WILL BE PUNISHED FOR CODING
+
+  SAVE THE DOCUMENT YOU MUST SAVE IN THE CORRECT FORMAT FOR THE NEXT DEV
+
+  ALWAYS FOLLOW BEST PRACTISES