• NEVER skip the initial test coverage step - Refactoring without test coverage first leads to undetected breakage. Always run

  accelint-ts-testing

  before any code changes.
• NEVER run best-practices and performance sequentially - Running them separately creates contradictory recommendations for the same code. Always run in parallel to see merged suggestions.
• NEVER present issues one-by-one for approval - Always show ALL issues in a numbered table first, then display each issue's detailed before/after code, THEN ask for numbered list acceptance. This prevents wildly inconsistent presentations and allows users to spot conflicts across parallel processes.
• NEVER skip displaying the overview table - BLOCKING: You MUST display the emoji severity table with ALL issues before showing any detailed changes. No exceptions.
• NEVER ask for approval before showing all detailed changes - BLOCKING: You MUST show the complete before/after code for EVERY issue before asking "Apply which issues?"
• NEVER auto-apply all recommendations - Each change needs user approval (accept/deny/other) to maintain code ownership and prevent unwanted modifications.
• NEVER run one-off commands instead of documented verification commands - The audit-process file documents EXACT verification commands. Use those commands verbatim. Never improvise with

  npm test

  ,

  bun test

  , or similar unless they match the documented commands exactly.
• NEVER skip saving progress after completing a step - After EVERY step completion, immediately save detailed progress to audit-process file BEFORE moving to next step. Context limits will break otherwise.
• NEVER skip the 100-pass PBT verification - When property-based tests are added, you MUST run the test suite 100 times to verify stability. Random failures are common with PBT. This is a blocking requirement - do not proceed until 100 consecutive passes are achieved. Run the tests without coverage reporting on to increase speed and stability.
• NEVER lose progress when context runs out - Save detailed progress to audit-process file after each step. Context limits are guaranteed in large audits.
• NEVER assume property-based tests are stable - Random test failures are common with PBT. Run new property tests 100 times to verify stability before accepting. Run the tests without coverage reporting on to increase speed and stability.
• NEVER add PERF comments everywhere - Only add

  // PERF:

  comments when they provide meaningful insight that future developers wouldn't discover on their own.
• NEVER mark a file complete without all 9 steps - Partial audits leave files in inconsistent states. Complete all steps or mark as in-progress.
• NEVER move on from a broken build - Fix compilation errors, test failures, and lint issues immediately before proceeding to the next step.
• NEVER run audit in main branch - Always create an isolated worktree to prevent conflicts with parallel audits and allow safe experimentation.

• Is this path valid and accessible? Verify the file or directory exists before creating TODO lists.
• Are there test and build commands available? Check package.json or ask user for verification commands before starting.
• How many files will this audit? Large directories (>5 files) will require multiple sessions. Set expectations upfront.

• Is this a new audit or resuming? Check for existing audit-process files in

  .agents/audit/

  before creating new ones.
• Will this fit in one session? Estimate ~1-5 files per session max. Plan for resumption if larger.
• Are verification commands known? Document exact test/build/lint commands in the audit-process file from the start.

• What's the user's risk tolerance? Some users want every suggestion, others only critical fixes. Clarify before first interactive prompt.
• Should performance micro-optimizations be included? 1.05x-1.15x gains may not be worth code churn for all projects.

1. Initialize - Create TODO list and audit tracking files
2. For each file - Run 9-step audit process with user approval
3. Track progress - Save after each step to survive context limits
4. Archive completed - Move finished files to history file

.agents/audit/

.agents/audit/

.gitignore

1. Check completion status:
   • Review "Current Status" section for files completed vs remaining
   • Review "Files to Audit" section for pending/completed breakdown
   • If all files are marked "Completed", the audit is done
2. Check worktree status (backwards compatibility):
   • If "Worktree Information" section exists: verify worktree still exists and switch to it
   • If no worktree documented: this is a legacy audit from before worktree support. Continue in current branch without creating a worktree.
   • Note: Only NEW audits created after this feature will use worktrees
3. Continue from "Resume Instructions" section

1. Create worktree with timestamped branch:
   bash

   timestamp=$(date +%Y%m%d-%H%M%S)
   git worktree add .agents/worktrees/audit-${timestamp} -b audit/${timestamp}

2. Switch to the worktree directory:
   bash

   cd .agents/worktrees/audit-${timestamp}

3. Log the worktree path - You will work in this directory for the entire audit

.agents/worktrees/

.agents/audit/

.agents/audit/

assets/audit-process-template.md

assets/audit-history-template.md

• Go back to the original repository root:

  cd $(git rev-parse --show-toplevel)

• Create

  .agents/audit/audit-process-${timestamp}.md

  (use same timestamp as worktree)
• Create

  .agents/audit/audit-history-${timestamp}.md

  (same timestamp)
• Return to the worktree:

  cd .agents/worktrees/audit-${timestamp}

.agents/audit/

.test.ts

.spec.ts

.bench.ts

• Add worktree path and branch to "Worktree Information" section
• Add all files to "Files to Audit" section as "Pending"
• Document the exact verification commands (test/build/lint)
• Set "Current File" to first pending file
• Save the file

/skill accelint-ts-testing <file-path>

You MUST complete all three checkpoints before proceeding:

1. ✅ Display emoji severity table with ALL issues (see "Interactive Change Approval Pattern")
2. ✅ Show detailed before/after code for EVERY issue
3. ✅ Ask "Apply which issues?" with numbered list acceptance NO EXCEPTIONS. If you skip any checkpoint, you are violating the workflow.

• Apply accepted changes
• BLOCKING REQUIREMENT: If property-based tests added, run verification:
  bash

  # Run test suite 100 times to verify PBT stability
  for i in {1..100}; do <test-command> || break; done

  • Run the tests without coverage reporting to prevent coverage conflicts
  • If ANY run fails, examine the seed that failed
  • Fix test properties (add constraints to arbitraries: date ranges, filtered NaNs, safe strings)
  • Re-run 100 times until 100 consecutive passes achieved
  • DO NOT proceed to Step 3 until this verification passes
• Document findings in "Current File - Detailed Progress" section
• Update status to show Step 1 ✅, Step 2 ✅
• SAVE PROGRESS to audit-process file NOW before continuing

/skill accelint-ts-best-practices <file-path>
/skill accelint-ts-performance <file-path>

• Review both sets of recommendations
• If recommendations overlap:
  • Try to merge them into single fix if possible
  • If conflicting, present both and let user choose

You MUST complete all three checkpoints before proceeding:

1. ✅ Display emoji severity table with ALL issues from BOTH skills (see "Interactive Change Approval Pattern")
2. ✅ Show detailed before/after code for EVERY issue
3. ✅ Ask "Apply which issues?" with numbered list acceptance NO EXCEPTIONS. If you skip any checkpoint, you are violating the workflow.

• Apply accepted changes
• Add

  // PERF:

  comments only where they add genuine insight
• Document in "Current File - Detailed Progress"
• Update status to show Step 3 ✅, Step 4 ✅
• SAVE PROGRESS to audit-process file NOW before continuing

/skill accelint-ts-documentation <file-path>

You MUST complete all three checkpoints before proceeding:

1. ✅ Display emoji severity table with ALL documentation issues (see "Interactive Change Approval Pattern")
2. ✅ Show detailed before/after code for EVERY issue
3. ✅ Ask "Apply which issues?" with numbered list acceptance NO EXCEPTIONS. If you skip any checkpoint, you are violating the workflow.

• Apply accepted changes
• Run final verification to ensure docs didn't break anything (use EXACT commands from audit-process file)
• Document in "Current File - Detailed Progress"
• Update status to show Step 7 ✅, Step 8 ✅
• SAVE PROGRESS to audit-process file NOW before continuing to Step 3 (Archive)

1. Move detailed progress to history file
   • Copy entire "Current File - Detailed Progress" section
   • Append to audit-history file
   • Add summary statistics at end of file's section
2. Update audit-process file
   • Mark file as "Completed" in "Files to Audit" section
   • Clear "Current File - Detailed Progress" section
   • Set "Current File" to next pending file
   • Update "Resume Instructions" for next file
   • Update "Current Status" counts
3. Save both files

• Return to Step 2 for next file
• Monitor context usage - if approaching limit, stop and save progress

1. Run final verification in worktree:
   • Run final full test suite + lint verification
   • Ensure all changes pass before merging
2. Merge worktree back to original branch:
   bash

   # Extract timestamp from current worktree directory name
   # We're in .agents/worktrees/audit-YYYYMMDD-HHMMSS
   timestamp=$(basename $(pwd) | sed 's/audit-//')
   
   # Get the original branch from this audit's process file (in original repo)
   repo_root=$(git rev-parse --show-toplevel)
   audit_process_file="${repo_root}/.agents/audit/audit-process-${timestamp}.md"
   original_branch=$(grep "^**Original Branch:**" ${audit_process_file} | cut -d'`' -f2)
   
   # Commit all changes in worktree
   git add -A
   git commit -m "refactor: complete TypeScript audit
   
   - Improved test coverage across all files
   - Applied type safety and best practice improvements
   - Optimized performance where beneficial
   - Enhanced documentation
   
   Co-Authored-By: {current_model}"
   
   # Switch back to original branch
   cd "${repo_root}"
   git checkout ${original_branch}
   
   # Merge the audit branch
   git merge --no-ff audit/${timestamp}

3. Clean up worktree:
   bash

   # Remove the worktree (use the timestamp extracted earlier)
   git worktree remove .agents/worktrees/audit-${timestamp}
   
   # Optionally delete the audit branch
   git branch -d audit/${timestamp}

4. Update audit-process file with completion:
   • Add completion summary with total statistics
   • Document merge commit hash
   • Mark audit as "✅ COMPLETE - Merged to ${original_branch}"
5. Report results:
   • Total statistics across all files
   • Merge commit information
   • Confirmation that worktree was cleaned up

• [ ]

  - Pending (not started)

• [x]

  - Completed (all 9 steps done, moved to history)

• ✅ - Complete
• 🔄 - In Progress
• ⏸️ - Pending (not started)

undefined

• Do NOT load README.md - It contains user-facing documentation that duplicates this file. All Agent instructions are contained in SKILL.md.
• Worktree location: All audit work happens in

  .agents/worktrees/audit-${timestamp}

  to avoid conflicts with the gitignored

  .agents/audit/

  directory.
• Tracking files location: Audit process and history files are stored in the original repository's

  .agents/audit/

  directory (gitignored) and are NOT committed with audit changes.
• Property-based test stability: If property tests fail randomly, check the exact seed that failed and verify the fix against that seed. Add constraints to arbitraries (date ranges, filtered NaNs, safe strings) to prevent false positives.
• Parallel skill execution: When running ts-best-practices and ts-performance in parallel, wait for BOTH to complete before presenting recommendations. This allows you to identify and merge overlapping suggestions.
• Context window management: Audit-process files are designed to survive context limits. After completing each step, save progress. If you must stop mid-file, document exactly which step you're on and what the next action should be.
• Build failures block progress: Never proceed to the next step if verification commands fail. Fix the issue or roll back the change first.
• PERF comment guidelines: Only add performance comments when the optimization is non-obvious. "Using for...of instead of map" doesn't need a comment. "Memoizing deserializer to avoid repeated JSON parsing" does.
• History file is write-only: Only read audit-history file if you need to understand a previous decision or consider reverting a change. Otherwise, it's purely archival.