nitm-ai-dev-toolkit 3.0.15

package/src/repo/hooks/ponytail-runtime.js

@@ -0,0 +1,51 @@
+const fs = require('fs');
+const path = require('path');
+const { getClaudeDir } = require('./ponytail-config');
+
+const STATE_FILE = '.ponytail-active';
+const isCopilot = Boolean(process.env.COPILOT_PLUGIN_DATA);
+const isCodex = !isCopilot && Boolean(process.env.PLUGIN_DATA);
+
+let stateDir = getClaudeDir();
+if (isCodex) stateDir = process.env.PLUGIN_DATA;
+if (isCopilot) stateDir = process.env.COPILOT_PLUGIN_DATA;
+
+const statePath = path.join(stateDir, STATE_FILE);
+
+function setMode(mode) {
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+  fs.writeFileSync(statePath, mode);
+}
+
+function clearMode() {
+  try { fs.unlinkSync(statePath); } catch (e) {}
+}
+
+function writeHookOutput(event, mode, context = '') {
+  if (isCopilot) {
+    // Copilot reads additionalContext on SessionStart; ignores output elsewhere.
+    process.stdout.write(JSON.stringify(
+      event === 'SessionStart' && context ? { additionalContext: context } : {}));
+    return;
+  }
+  if (isCodex) {
+    const output = { systemMessage: `PONYTAIL:${mode.toUpperCase()}` };
+    if (context) {
+      output.hookSpecificOutput = {
+        hookEventName: event,
+        additionalContext: context,
+      };
+    }
+    process.stdout.write(JSON.stringify(output));
+    return;
+  }
+  process.stdout.write(context);
+}
+
+module.exports = {
+  clearMode,
+  isCodex,
+  isCopilot,
+  setMode,
+  writeHookOutput,
+};

package/src/repo/hooks/ponytail-statusline.ps1

@@ -0,0 +1,21 @@
+# CLAUDE_CONFIG_DIR overrides ~/.claude, matching where the hooks write the flag (issue #34)
+$ClaudeDir = if ($env:CLAUDE_CONFIG_DIR) { $env:CLAUDE_CONFIG_DIR } else { Join-Path $HOME ".claude" }
+$Flag = Join-Path $ClaudeDir ".ponytail-active"
+if (-not (Test-Path $Flag)) {
+    exit 0
+}
+
+$Mode = ""
+try {
+    $Mode = (Get-Content $Flag -ErrorAction Stop | Select-Object -First 1).Trim()
+} catch {
+    exit 0
+}
+
+$Esc = [char]27
+if ([string]::IsNullOrEmpty($Mode) -or $Mode -eq "full") {
+    [Console]::Write("${Esc}[38;5;108m[PONYTAIL]${Esc}[0m")
+} else {
+    $Suffix = $Mode.ToUpperInvariant()
+    [Console]::Write("${Esc}[38;5;108m[PONYTAIL:$Suffix]${Esc}[0m")
+}

package/src/repo/hooks/ponytail-statusline.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# CLAUDE_CONFIG_DIR overrides ~/.claude, matching where the hooks write the flag (issue #34)
+flag="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/.ponytail-active"
+[ -f "$flag" ] || exit 0
+
+mode=$(head -n1 "$flag" | tr -d '[:space:]')
+
+if [ -z "$mode" ] || [ "$mode" = "full" ]; then
+    printf '\033[38;5;108m[PONYTAIL]\033[0m'
+else
+    printf '\033[38;5;108m[PONYTAIL:%s]\033[0m' "$(printf '%s' "$mode" | tr '[:lower:]' '[:upper:]')"
+fi

package/src/repo/templates/README.md

@@ -0,0 +1,80 @@
+# Documentation Templates
+
+This folder contains templates for project documentation. Copy these templates when creating new feature or fix documentation.
+
+## Available Templates
+
+- **monthly-fix-log.template.md** - Template for monthly fix logs (YYYY-MM.md format)
+- **feature-spec.template.md** - Template for feature specifications
+- **feature-plan.template.md** - Template for feature implementation plans
+- **complex-fix-spec.template.md** - Template for complex fix specifications
+- **complex-fix-plan.template.md** - Template for complex fix implementation plans
+- **adr.template.md** - Template for Architecture Decision Records
+
+## Usage
+
+### Monthly Fix Logs
+
+```bash
+# Copy template to create new monthly log
+cp templates/monthly-fix-log.template.md docs/fixes/2026-01.md
+
+# Edit the file and replace placeholders:
+# - {{MONTH_NAME}} → January
+# - {{YEAR}} → 2026
+# - {{YYYY-MM-DD}} → Actual dates
+```
+
+### Feature Documentation
+
+```bash
+# Create feature folder
+mkdir -p docs/features/ISSUE-123-FEATURE-NAME
+
+# Copy templates
+cp templates/feature-spec.template.md docs/features/ISSUE-123-FEATURE-NAME/spec.md
+cp templates/feature-plan.template.md docs/features/ISSUE-123-FEATURE-NAME/plan.md
+
+# Edit files and replace placeholders
+```
+
+### Complex Fix Documentation
+
+```bash
+# Create fix folder
+mkdir -p docs/fixes/ISSUE-456-COMPLEX-FIX
+
+# Copy templates
+cp templates/complex-fix-spec.template.md docs/fixes/ISSUE-456-COMPLEX-FIX/spec.md
+cp templates/complex-fix-plan.template.md docs/fixes/ISSUE-456-COMPLEX-FIX/plan.md
+
+# Edit files and replace placeholders
+```
+
+### Architecture Decision Records
+
+```bash
+# Copy ADR template
+cp templates/adr.template.md docs/architecture/0001-decision-title.md
+
+# Edit and replace placeholders
+```
+
+## Placeholder Reference
+
+Common placeholders used in templates:
+
+- `{{MONTH_NAME}}` - Full month name (e.g., January, February)
+- `{{YEAR}}` - Four-digit year (e.g., 2026)
+- `{{YYYY-MM-DD}}` - ISO date format (e.g., 2026-01-21)
+- `{{YYYY-MM}}` - Year and month (e.g., 2026-01)
+- `{{ISSUE_ID}}` - Issue tracker ID (e.g., ISSUE-123, JIRA-456)
+- `{{FEATURE_NAME}}` - Feature name
+- `{{FIX_NAME}}` - Fix name
+- `{{DATE}}` - Current date or last update date
+- `{{ISSUE_TRACKER}}` - Issue tracker name (e.g., Linear, Jira)
+- `{{ISSUE_TRACKER_URL}}` - Full URL to issue tracker ticket
+
+## Automated Creation
+
+Use the `/spec` and `/plan` commands to automatically create documentation from these templates with placeholders filled in.

package/src/repo/templates/adr.template.md

@@ -0,0 +1,162 @@
+# ADR-{{ADR_NUMBER}}: {{DECISION_TITLE}}
+
+**Status:** Proposed | Accepted | Deprecated | Superseded
+**Date:** {{DATE}}
+**Author:** {{AUTHOR}}
+**Deciders:** {{DECIDERS}}
+**Technical Story:** {{ISSUE_ID}}
+
+## Context
+
+Describe the context and problem statement. What is the issue that we're seeing that is motivating this decision or change?
+
+### Background
+
+Provide any relevant background information:
+
+- Current state of the system
+- Technical constraints
+- Business requirements
+- Timeline pressures
+
+### Problem Statement
+
+In 1-2 sentences, what problem are we trying to solve?
+
+## Decision Drivers
+
+What factors are important in making this decision?
+
+- **Driver 1:** Description
+- **Driver 2:** Description
+- **Driver 3:** Description
+- **Driver 4:** Description
+
+## Considered Options
+
+### Option 1: {{OPTION_1_NAME}}
+
+**Description:** Brief description of the approach.
+
+**Pros:**
+
+- Pro 1
+- Pro 2
+
+**Cons:**
+
+- Con 1
+- Con 2
+
+**Estimated Effort:** X days/weeks
+
+### Option 2: {{OPTION_2_NAME}}
+
+**Description:** Brief description of the approach.
+
+**Pros:**
+
+- Pro 1
+- Pro 2
+
+**Cons:**
+
+- Con 1
+- Con 2
+
+**Estimated Effort:** X days/weeks
+
+### Option 3: {{OPTION_3_NAME}}
+
+**Description:** Brief description of the approach.
+
+**Pros:**
+
+- Pro 1
+- Pro 2
+
+**Cons:**
+
+- Con 1
+- Con 2
+
+**Estimated Effort:** X days/weeks
+
+## Decision Outcome
+
+### Chosen Option
+
+**Option X: {{CHOSEN_OPTION_NAME}}**
+
+### Rationale
+
+Explain why this option was chosen:
+
+- Reason 1
+- Reason 2
+- Reason 3
+
+### Trade-offs Accepted
+
+What are we giving up by choosing this option?
+
+- Trade-off 1
+- Trade-off 2
+
+## Consequences
+
+### Positive
+
+- Positive consequence 1
+- Positive consequence 2
+
+### Negative
+
+- Negative consequence 1
+- Negative consequence 2
+
+### Neutral
+
+- Neutral consequence 1
+
+## Implementation
+
+### Action Items
+
+- [ ] Action item 1
+- [ ] Action item 2
+- [ ] Action item 3
+
+### Migration Plan
+
+If applicable, describe how to migrate from current state to new state.
+
+### Rollback Plan
+
+If applicable, describe how to rollback if needed.
+
+## Validation
+
+How will we know if this decision was successful?
+
+- Success metric 1
+- Success metric 2
+
+## Related Decisions
+
+- [ADR-XXX](./ADR-XXX-title.md) - Related decision
+- [ADR-YYY](./ADR-YYY-title.md) - Superseded by this ADR
+
+## References
+
+- [Link to relevant documentation]
+- [Link to technical specification]
+- [Link to discussion thread]
+
+---
+
+## Changelog
+
+| Date     | Change           |
+| -------- | ---------------- |
+| {{DATE}} | Initial proposal |

package/src/repo/templates/complex-fix-plan.template.md

@@ -0,0 +1,162 @@
+# Fix Implementation Plan: {{FIX_NAME}}
+
+**Issue:** {{ISSUE_ID}}
+**Spec:** [spec.md](spec.md)
+**Author:** {{AUTHOR}}
+**Created:** {{DATE}}
+**Priority:** P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
+**Status:** Planning | In Progress | In Review | Deployed
+
+## Overview
+
+Brief summary of the fix and implementation approach.
+
+## Prerequisites
+
+- [ ] Root cause confirmed in spec
+- [ ] Impact assessment complete
+- [ ] Stakeholders notified
+- [ ] Rollback plan ready
+
+## Implementation Steps
+
+### Step 1: Immediate Mitigation (if needed)
+
+**Timeline:** ASAP
+
+**Tasks:**
+
+- [ ] Apply temporary workaround
+- [ ] Notify affected users
+- [ ] Enable monitoring
+
+### Step 2: Prepare Fix
+
+**Timeline:** X hours
+
+**Files to modify:**
+
+- `path/to/file1.{{FILE_EXTENSION}}`
+- `path/to/file2.{{FILE_EXTENSION}}`
+
+**Tasks:**
+
+- [ ] Create feature branch from {{DEFAULT_BRANCH}}
+- [ ] Implement code changes
+- [ ] Add/update tests
+- [ ] Update documentation
+
+**Code Changes:**
+
+```{{FILE_EXTENSION}}
+// Describe the key changes
+```
+
+### Step 3: Testing
+
+**Timeline:** X hours
+
+**Tasks:**
+
+- [ ] Run unit tests
+- [ ] Run integration tests
+- [ ] Manual verification of fix
+- [ ] Verify no regression
+
+**Test Commands:**
+
+```bash
+{{TEST_COMMAND}}
+```
+
+### Step 4: Code Review
+
+**Timeline:** X hours
+
+**Tasks:**
+
+- [ ] Create pull request
+- [ ] Address review comments
+- [ ] Get approval from {{REVIEWER}}
+
+### Step 5: Deployment
+
+**Timeline:** X hours
+
+**Tasks:**
+
+- [ ] Deploy to staging
+- [ ] Verify fix in staging
+- [ ] Deploy to production
+- [ ] Monitor for 24 hours
+
+## Rollback Plan
+
+If the fix causes issues:
+
+1. **Immediate:** Revert commit `{{COMMIT_HASH}}`
+2. **Database:** Run rollback migration (if applicable)
+3. **Cache:** Clear cache keys: `{{CACHE_KEYS}}`
+4. **Notify:** Alert team via {{NOTIFICATION_CHANNEL}}
+
+**Rollback command:**
+
+```bash
+git revert {{COMMIT_HASH}}
+{{DEPLOY_COMMAND}}
+```
+
+## Verification
+
+### Success Criteria
+
+- [ ] Original bug no longer reproducible
+- [ ] No new errors in logs
+- [ ] Performance metrics stable
+- [ ] User reports resolved
+
+### Monitoring
+
+| Metric        | Expected Value | Alert Threshold |
+| ------------- | -------------- | --------------- |
+| Error rate    | < 0.1%         | > 1%            |
+| Response time | < 200ms        | > 500ms         |
+
+## Communication
+
+### Stakeholder Updates
+
+| Stakeholder | Update Method | When            |
+| ----------- | ------------- | --------------- |
+| Engineering | Slack         | On fix complete |
+| Product     | Email         | On deployment   |
+| Customers   | Status page   | If applicable   |
+
+### Post-Mortem
+
+- [ ] Schedule post-mortem meeting
+- [ ] Document lessons learned
+- [ ] Create follow-up tickets for improvements
+
+## Timeline
+
+| Phase           | Target Time | Actual Time | Status      |
+| --------------- | ----------- | ----------- | ----------- |
+| Mitigation      | +1 hour     |             | Not Started |
+| Fix Development | +4 hours    |             | Not Started |
+| Testing         | +2 hours    |             | Not Started |
+| Code Review     | +2 hours    |             | Not Started |
+| Deployment      | +1 hour     |             | Not Started |
+| Monitoring      | +24 hours   |             | Not Started |
+
+## Notes
+
+Additional notes, edge cases discovered, or decisions made during implementation.
+
+---
+
+## Progress Log
+
+| Time     | Update       |
+| -------- | ------------ |
+| {{TIME}} | Plan created |

package/src/repo/templates/complex-fix-spec.template.md

@@ -0,0 +1,163 @@
+# Fix Specification: {{FIX_NAME}}
+
+**Issue:** {{ISSUE_ID}}
+**Author:** {{AUTHOR}}
+**Created:** {{DATE}}
+**Severity:** Critical | High | Medium | Low
+**Status:** Investigating | Root Cause Found | Fix In Progress | Resolved
+
+## Problem Summary
+
+Brief one-paragraph description of the bug or issue.
+
+## Symptoms
+
+### Observed Behavior
+
+What users or systems are experiencing:
+
+- Symptom 1
+- Symptom 2
+- Symptom 3
+
+### Expected Behavior
+
+What should happen instead:
+
+- Expected behavior 1
+- Expected behavior 2
+
+### Reproduction Steps
+
+1. Step 1
+2. Step 2
+3. Step 3
+4. Observe: [describe the bug]
+
+### Environment
+
+- **Environment:** Production / Staging / Development
+- **Version:** {{VERSION}}
+- **Browser/OS:** (if applicable)
+- **User Impact:** X users affected
+
+## Root Cause Analysis
+
+### Investigation Timeline
+
+| Time     | Action           | Finding                  |
+| -------- | ---------------- | ------------------------ |
+| {{TIME}} | Reviewed logs    | Found error pattern      |
+| {{TIME}} | Checked database | Data inconsistency found |
+
+### Root Cause
+
+Detailed explanation of why the bug occurred:
+
+```
+[Code snippet or configuration showing the root cause]
+```
+
+**Why it happened:**
+
+- Reason 1
+- Reason 2
+
+### Contributing Factors
+
+- Factor 1 (e.g., missing validation)
+- Factor 2 (e.g., race condition)
+- Factor 3 (e.g., edge case not handled)
+
+## Impact Assessment
+
+### Affected Components
+
+| Component       | Impact Level | Description       |
+| --------------- | ------------ | ----------------- |
+| {{COMPONENT_1}} | High/Med/Low | How it's affected |
+| {{COMPONENT_2}} | High/Med/Low | How it's affected |
+
+### Data Impact
+
+- Was any data corrupted? Yes / No
+- If yes, describe scope and recovery plan
+
+### Business Impact
+
+- Users affected: X
+- Revenue impact: $X or N/A
+- SLA breach: Yes / No
+
+## Proposed Solution
+
+### Approach
+
+Describe the fix approach at a high level.
+
+### Code Changes
+
+**File:** `path/to/file.{{FILE_EXTENSION}}`
+
+Before:
+
+```{{FILE_EXTENSION}}
+// Problematic code
+```
+
+After:
+
+```{{FILE_EXTENSION}}
+// Fixed code
+```
+
+### Additional Changes
+
+- [ ] Database migration required
+- [ ] Configuration change required
+- [ ] Cache invalidation required
+
+## Testing Requirements
+
+### Regression Tests
+
+- [ ] Test that the specific bug is fixed
+- [ ] Test related functionality still works
+- [ ] Test edge cases
+
+### Test Cases
+
+| Test Case             | Input | Expected Output    |
+| --------------------- | ----- | ------------------ |
+| Original bug scenario | X     | Y (fixed behavior) |
+| Edge case 1           | A     | B                  |
+| Edge case 2           | C     | D                  |
+
+## Prevention
+
+### How to Prevent Recurrence
+
+- [ ] Add validation for X
+- [ ] Improve error handling
+- [ ] Add monitoring/alerting
+- [ ] Update documentation
+
+### Process Improvements
+
+- Lesson learned 1
+- Lesson learned 2
+
+## References
+
+- [Issue Tracker]({{ISSUE_TRACKER_URL}})
+- [Related PR](link)
+- [Error Logs](link)
+- [Monitoring Dashboard](link)
+
+---
+
+## Changelog
+
+| Date     | Author     | Change Description    |
+| -------- | ---------- | --------------------- |
+| {{DATE}} | {{AUTHOR}} | Initial investigation |