@devran-ai/kit 4.1.0

package/.agent/skills/plan-writing/plan-schema.md

@@ -0,0 +1,119 @@
+# Plan Quality Schema
+
+> Defines the mandatory structure and scoring rubric for implementation plans.
+> Every plan produced by the `/plan` workflow MUST satisfy this schema.
+
+---
+
+## Task Size Classification
+
+Before applying the schema, classify the task:
+
+| Size | Criteria | Required Tiers |
+|------|----------|----------------|
+| **Trivial** | 1-2 files, <30 minutes estimated effort | Tier 1 only |
+| **Medium** | 3-10 files, 1-4 hours estimated effort | Tier 1 + Tier 2 |
+| **Large** | 10+ files, multi-day effort | Tier 1 + Tier 2 + architect consultation |
+
+---
+
+## Tier 1 — Always Required
+
+Every plan, regardless of task size, MUST include these sections:
+
+| # | Section | Description | Points |
+|---|---------|-------------|--------|
+| 1 | **Context & Problem Statement** | Why this change is needed. 2-3 sentences covering the problem, impact, and motivation. | 10 |
+| 2 | **Goals & Non-Goals** | What the plan achieves (goals) and what is explicitly out of scope (non-goals). Prevents scope creep. | 10 |
+| 3 | **Implementation Steps** | Ordered tasks with exact file paths, specific actions, and verification criteria per step. | 10 |
+| 4 | **Testing Strategy** | Test types required (unit, integration, e2e), coverage targets, key test cases. Reference `.agent/rules/testing.md`. | 10 |
+| 5 | **Security Considerations** | Applicable security requirements from `.agent/rules/security.md`. If genuinely not applicable, state `N/A — [one-line justification]`. | 10 |
+| 6 | **Risks & Mitigations** | At least 1 risk with severity (Low/Medium/High) and concrete mitigation strategy. | 5 |
+| 7 | **Success Criteria** | Measurable definition of done. Checkboxes with specific, verifiable outcomes. | 5 |
+
+**Tier 1 Maximum: 60 points**
+
+---
+
+## Tier 2 — Required for Medium & Large Tasks
+
+Plans for tasks affecting 3+ files or requiring 1+ hours MUST also include:
+
+| # | Section | Description | Points |
+|---|---------|-------------|--------|
+| 8 | **Architecture Impact** | Affected components/modules, integration points, dependency changes. Include component diagram for Large tasks. | 4 |
+| 9 | **API / Data Model Changes** | New or modified endpoints, request/response schemas, database schema changes. | 3 |
+| 10 | **Rollback Strategy** | How to undo the change if deployment fails or defects are discovered post-release. | 3 |
+| 11 | **Observability** | Logging additions, metrics to track, alerting changes, monitoring dashboards affected. | 2 |
+| 12 | **Performance Impact** | Bundle size changes, query performance, latency estimates, memory usage. | 2 |
+| 13 | **Documentation Updates** | Which docs need changing (ROADMAP, CHANGELOG, README, API docs, ADRs). Reference `.agent/rules/documentation.md`. | 2 |
+| 14 | **Dependencies** | What blocks this work (prerequisites). What depends on this work (downstream impact). | 2 |
+| 15 | **Alternatives Considered** | At least 1 rejected approach with reasoning for why the chosen approach is superior. | 2 |
+
+**Tier 2 Maximum: 20 points (added to Tier 1)**
+
+---
+
+## Domain Enhancement Scoring
+
+When the loading engine matches specific domains (e.g., frontend, backend, security), the corresponding domain enhancer sections from `domain-enhancers.md` MUST be included. Domain sections are scored as **bonus points** on top of the tier maximum:
+
+| Condition | Scoring Impact |
+|-----------|---------------|
+| Domain matched and enhancer section present + substantive | +2 bonus points per domain |
+| Domain matched but enhancer section missing | -2 penalty per missing domain (deducted from tier score) |
+| Domain matched with "N/A — [valid reason]" | No bonus, no penalty |
+| No domains matched | No impact |
+
+**Maximum domain bonus**: +6 points (3 domains × 2 points each).
+
+Domain scoring does NOT change the pass threshold — it provides additional quality signal. A plan can PASS without domain bonuses but will be penalized if matched domains are ignored.
+
+---
+
+## Scoring
+
+| Task Size | Max Score | Pass Threshold (70%) |
+|-----------|-----------|---------------------|
+| Trivial | 60 | 42 |
+| Medium | 80 | 56 |
+| Large | 100 | 70 |
+
+**Score Calculation**:
+- A section earns full points when present and substantively populated
+- A section earns zero points when missing or contains only placeholder text
+- "N/A" with a valid justification counts as populated (earns full points)
+
+**Verdict**:
+- **PASS**: Score >= 70% of tier maximum
+- **REVISE**: Score < 70% — identify missing sections and revise (max 2 revision cycles)
+
+---
+
+## Cross-Cutting Mandate
+
+Regardless of task domain, these sections MUST be substantively addressed in every plan:
+
+1. **Security Considerations** (Tier 1, #5) — Reference `.agent/rules/security.md`
+2. **Testing Strategy** (Tier 1, #4) — Reference `.agent/rules/testing.md`
+3. **Documentation Updates** (Tier 2, #13) — Reference `.agent/rules/documentation.md`
+
+If a cross-cutting section is genuinely not applicable, the plan MUST state:
+```
+N/A — [specific reason this concern does not apply to this task]
+```
+
+**NEVER silently omit a cross-cutting section.** Silent omission is a plan defect.
+
+---
+
+## Alignment Verification
+
+Every plan MUST include an alignment check against operating constraints:
+
+| Check | Question |
+|-------|----------|
+| Operating Constraints | Does this respect Trust > Optimization? |
+| Existing Patterns | Does this follow project conventions? |
+| Rules Consulted | Which rule files were reviewed? |
+| Coding Style | Does this comply with `.agent/rules/coding-style.md`? |

package/.agent/skills/pr-toolkit/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: pr-toolkit
+description: Pull request lifecycle domain knowledge — branch strategy detection, PR size classification, confidence-scored review, git-aware context, PR analytics, dependency management, and split/merge/describe operations.
+version: 2.0.0
+triggers: [pr, pull-request, review, merge, branch, code-review]
+allowed-tools: Read, Grep, Bash
+---
+
+# PR Toolkit Skill
+
+> **Purpose**: Domain knowledge for complete PR lifecycle — creation, review, remediation, merge, split, describe, analytics, and dependency management.
+
+---
+
+## 1. Branch Strategy Detection
+
+Detect branching model before any PR operation.
+
+```bash
+git branch -r | grep -E 'origin/(dev|develop)$'
+git branch -r | grep -E 'origin/release/'
+```
+
+| Indicator | Strategy |
+|:---|:---|
+| `dev`/`develop` exists | GitFlow — features merge to dev, dev merges to main at release |
+| Only `main`/`master` | Trunk-Based — short-lived branches merge to main |
+| `release/*` branches | GitFlow (full) with release branch phase |
+
+### GitFlow Target Validation
+
+| Source | Valid Target | Invalid → Action |
+|:---|:---|:---|
+| `feature/*`, `bugfix/*`, `chore/*`, `docs/*` | `dev`/`develop` | `main` → **BLOCK**, redirect to dev |
+| `hotfix/*` | `main`/`master` | Proceed (emergency) |
+| `release/*`, `dev` | `main`/`master` | Proceed |
+
+Trunk-based: any short-lived branch → `main`/`master`.
+
+---
+
+## 2. PR Size Classification
+
+| Label | Files | Lines | Review Time | Action |
+|:---|:---|:---|:---|:---|
+| **XS** | 1-5 | <100 | <15 min | Fast-track |
+| **S** | 6-15 | 100-300 | 15-30 min | Standard |
+| **M** | 16-30 | 300-700 | 30-60 min | Thorough |
+| **L** | 31-50 | 700-1500 | 1-2 hrs | Consider splitting |
+| **XL** | 50+ | 1500+ | 2+ hrs | **MUST split** — block |
+
+### Scope Coherence
+
+A PR must relate to ONE logical change. Violations (mixed feature+tooling, mixed feature+deps, multiple unrelated features) → split into focused PRs by type (`feat:`, `chore:`, `chore(deps):`, `docs:`).
+
+---
+
+## 3. Title Format
+
+Format: `type(scope): description` — conventional commits, lowercase, imperative mood, no period, <72 chars.
+
+**Branch parsing**: `feature/ABC-123-add-user-auth` → strip type prefix (`feature/`→`feat`) → strip ticket (`ABC-123-`) → first segment as scope → remaining as description → `feat(user): add user auth`. Fallback: first commit subject.
+
+---
+
+## 4. Review Framework
+
+### 6 Perspectives (sequential)
+
+1. **PR Hygiene**: title, body, size, scope coherence
+2. **Branch Strategy**: correct target, naming convention
+3. **Code Quality**: functions <50 lines, files <800, no deep nesting, error handling
+4. **Security**: secrets, input validation, injection, XSS, auth
+5. **Testing**: new code has tests, edge cases, coverage maintained
+6. **Architecture**: follows patterns, SOLID, clean dependencies
+
+### Severity Levels
+
+| Severity | Blocks Merge? |
+|:---|:---|
+| **CRITICAL** :red_circle: | Yes — security, data loss, crash |
+| **HIGH** :orange_circle: | Yes if 3+ — broken functionality |
+| **MEDIUM** :yellow_circle: | No — improvement suggestion |
+| **LOW** :blue_circle: | No — optional improvement |
+| **NIT** :white_circle: | No — style preference |
+
+**Verdict**: 0 CRITICAL + 0 HIGH → APPROVE | 0 CRITICAL + 1-2 HIGH → COMMENT | Any CRITICAL or 3+ HIGH → REQUEST_CHANGES
+
+---
+
+## 5. Fix Prioritization
+
+Priority: CRITICAL → HIGH → MEDIUM → LOW/NIT. Commit convention: `fix(review): address <finding>` or squash to `fix(review): address PR #N review findings`.
+
+After each fix: run affected tests, verify concern addressed. After all fixes: run full review pipeline, push, re-request review, summarize changes on PR.
+
+---
+
+## 6. PR Body Checklist
+
+Required: Summary (1-3 sentences), Changes (categorized list), Test Plan, Checklist. When applicable: Breaking Changes, Related Issues (`Closes #N`), Screenshots (UI changes).
+
+---
+
+## 7. Repository Health Signals
+
+Check: branch protection rules, PR template (`.github/pull_request_template.md`), CODEOWNERS, CI pipeline, auto-delete branches, default branch alignment.
+
+---
+
+## 8. Confidence Scoring
+
+Every finding gets confidence 0-100. Default threshold: 70 (High+Certain). `--strict`: 50. `--relaxed`: 90.
+
+| Score | Label | Action |
+|:---|:---|:---|
+| 90-100 | Certain | Always report |
+| 70-89 | High | Report (default threshold) |
+| 50-69 | Moderate | Suppress by default |
+| 0-49 | Low/Noise | Suppress |
+
+**Adjustments**: +30 OWASP match, +20 PR-introduced code, +15 file:line evidence, -15 existing codebase pattern, -20 style-only, -25 test/generated code.
+
+---
+
+## 9. PR Analytics
+
+Core metrics: Coding Time (<2d), Pickup Time (<4h), Review Time (<24h), Cycle Time (<3d), Merge Frequency (3-5/dev/week), Review Rounds (<2), PR Size median (100-300 LOC).
+
+DORA alignment: Deployment Frequency ↔ merge frequency, Lead Time ↔ cycle time, Change Failure Rate ↔ revert rate, MTTR ↔ hotfix cycle time.
+
+Staleness: <3d fresh, 3-7d aging (nudge), 7-14d stale (escalate), 14d+ abandoned (consider close).
+
+---
+
+## 10. Dependency Management
+
+`Depends-On: #42` in PR body. Rules: block merge on unmerged deps, cross-repo support, cycle detection (block both), transitive deps.
+
+---
+
+## 11. Split Strategy
+
+| Category | Detection | Sub-PR Type |
+|:---|:---|:---|
+| Feature code | `src/`, `lib/`, `app/` | `feat:` |
+| Tests | `tests/`, `*.test.*` | `test:` |
+| Config | `.agent/`, `.github/`, config | `chore:` |
+| Dependencies | `package.json`, lockfiles | `chore(deps):` |
+| Docs | `*.md`, `docs/` | `docs:` |
+| Styling | CSS/SCSS, themes | `style:` |
+| Infrastructure | Dockerfile, CI, terraform | `ci:`/`chore:` |
+
+Merge order: deps → config → feature → tests → docs.
+
+---
+
+## 12. Auto-Description
+
+Algorithm: title from branch (section 3) or commits → summary from commit aggregation → changes grouped by type → labels from file patterns → related issues from commit messages.
+
+Label mapping: `src/`→feature/bugfix, `tests/`→testing, `docs/`→documentation, CSS→styling, `.github/`→infrastructure, `package.json`→dependencies. Size labels: XS/S/M/L/XL per section 2.
+
+---
+
+## 13. Reviewer Comment Engagement
+
+Fetch from all 3 GitHub endpoints: `/pulls/{n}/reviews`, `/pulls/{n}/comments`, `/issues/{n}/comments`.
+
+Bots: `gemini-code-assist` (priority labels + suggested changes), `coderabbitai` (severity badges), `github-actions[bot]` (CI results), `sonarcloud[bot]` (quality gates), `dependabot[bot]` (CVEs).
+
+**Rules**: Valid+open → agree with attribution. Valid+fixed → acknowledge with SHA. Invalid → challenge with evidence. Duplicate → reference theirs. Missed → amplify.
+
+**Cross-file checks**: count headings vs items, category consistency, version strings, feature counts vs filesystem.

package/.agent/skills/production-readiness/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: production-readiness
+description: Production readiness audit domains, weighted scoring criteria, and check specifications for the /preflight workflow.
+version: 1.0.0
+triggers: [pre-deploy, pre-launch, milestone, production-readiness]
+allowed-tools: Read, Grep, Bash
+---
+
+# Production Readiness
+
+> **Purpose**: Assess project readiness for production across 10 audit domains
+> **Invoked by**: `/preflight` | **Reusable by**: `/retrospective`, `/deploy`
+
+---
+
+## Principles
+
+1. **Evidence over assertion** — every score backed by observable proof
+2. **Non-destructive** — checks don't modify source; verification commands may run
+3. **Fail-safe defaults** — unverifiable checks score 0
+4. **Domain independence** — each domain scored independently
+5. **Blocker precedence** — blocker rules override total score
+
+---
+
+## Domain Definitions
+
+### D1: Task Completeness (8 pts) — Skill: `plan-writing`
+
+ROADMAP/task tracker exists and current (2) | All milestone tasks complete (3) | No undocumented features (2) | No scope drift (1)
+
+### D2: User Journey Validation (10 pts) — Skills: `webapp-testing`, `testing-patterns`
+
+Critical flows identified, >=3 (2) | Happy path verified (3) | Error/edge handling (3) | Accessibility baseline (2)
+
+### D3: Implementation Correctness (10 pts) — Skills: `verification-loop`, `testing-patterns`
+
+Test suite passes (4) | Coverage >= target or 60% (2) | No dead code (2) | Features match specs (2)
+
+### D4: Code Quality (15 pts) — Skills: `verification-loop`, `clean-code` — Delegates to `/review`
+
+Lint passes (3) | Type check strict (3) | Build succeeds (3) | Style compliance (3) | Dependency health (3)
+
+### D5: Security & Privacy (18 pts) — Skill: `security-practices` — **Highest weight**
+
+No hardcoded secrets (4) | Dependency vuln scan (3) | Auth/authz audit (3) | Input validation all endpoints (3) | HTTPS + security headers (3) | Privacy/PII compliance (2)
+
+### D6: Configuration Readiness (8 pts) — Skills: `deployment-procedures`, `shell-conventions`
+
+Env vars documented (2) | No dev values in prod (2) | Secrets management defined (2) | Env-specific configs separated (2)
+
+### D7: Performance Baseline (8 pts) — Skill: `performance-profiling`
+
+Bundle size within budget (2) | No perf anti-patterns (2) | Core Web Vitals baseline (2) | API p95 <500ms (2)
+
+### D8: Documentation (5 pts) — Skill: `plan-writing`
+
+README with setup (2) | API docs (1) | Runbook (1) | CHANGELOG current (1)
+
+### D9: Infrastructure & CI/CD (10 pts) — Skills: `deployment-procedures`, `docker-patterns`
+
+CI passes (3) | Deploy strategy defined (2) | Rollback capability (3) | Health check endpoint (2)
+
+### D10: Observability & Monitoring (8 pts) — Skill: `deployment-procedures`
+
+Error tracking configured (3) | Structured logging (2) | Alerting for critical paths (2) | No PII in logs (1)
+
+---
+
+## Scoring Model
+
+| Domain | Weight | Max |
+|:---|:---|:---|
+| D1: Task Completeness | 8% | 8 |
+| D2: User Journey | 10% | 10 |
+| D3: Implementation | 10% | 10 |
+| D4: Code Quality | 15% | 15 |
+| D5: Security & Privacy | 18% | 18 |
+| D6: Configuration | 8% | 8 |
+| D7: Performance | 8% | 8 |
+| D8: Documentation | 5% | 5 |
+| D9: Infrastructure | 10% | 10 |
+| D10: Observability | 8% | 8 |
+| **Total** | **100%** | **100** |
+
+---
+
+## Go/No-Go Thresholds
+
+| Score | Status | Action |
+|:---|:---|:---|
+| >= 85 | Production Ready | Proceed to `/pr` -> `/deploy` |
+| 70-84 | Conditionally Ready | Fix medium issues, `--rescan` |
+| < 70 | Not Ready | Fix critical/high, `--rescan` |
+
+---
+
+## Blocker Rules (override total score)
+
+Evaluated BEFORE total score. Precedence: Zero Domain > Security Floor > Quality Floor > Total Score.
+
+| Rule | Condition | Override |
+|:---|:---|:---|
+| Zero Domain | Any domain scores 0 | Not Ready |
+| Security Floor | D5 < 50% (<9/18) | Not Ready |
+| Quality Floor | D4 < 50% (<=7/15) | Caps at Conditionally Ready |
+
+---
+
+## Evidence Requirements
+
+Every sub-check score must have: **file evidence** (path), **command output**, **observation** (specific detail), or **N/A justification**. Unsupported scores default to 0.
+
+---
+
+## Delta Comparison (`--rescan`)
+
+Load previous scorecard -> run full D1-D10 -> generate delta table (domain, previous, current, delta) -> highlight regressions with WARNING -> summary with updated verdict.
+
+---
+
+## Integration
+
+- **Primary**: `/preflight` workflow (Verify phase)
+- **Reusable**: `/retrospective` (sprint audit), `/deploy` (can reference D5, D6, D9)
+- **References**: 8 existing skills via delegation map

package/.agent/skills/security-practices/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: security-practices
+description: Application security best practices including Zero Trust principles, OAuth 2.0 / OpenID Connect flows, API security, supply chain security, and vulnerability prevention
+triggers: [context, security, auth, vulnerability]
+---
+
+# Security Practices Skill
+
+> **Purpose**: Apply security best practices to protect applications
+
+---
+
+## Core Security Checklist
+
+Apply OWASP Top 10 mitigations on every project: parameterized queries (injection), strong auth + MFA + rate limiting (broken auth), encryption at rest/transit (sensitive data), disable XML external entities (XXE), verify permissions every request (broken access), security headers + remove defaults (misconfig), sanitize output + CSP (XSS), validate input types (insecure deserialization), keep deps updated (components), log security events (logging).
+
+---
+
+## Authentication
+
+- **Passwords**: bcrypt (cost factor 12) or Argon2. Never store plaintext.
+- **JWT**: Short-lived access tokens (15min), longer refresh tokens (7d) stored in httpOnly/Secure/SameSite cookies. Access tokens in memory only.
+- **MFA**: Require for admin and sensitive operations.
+
+---
+
+## Input Validation & Output Sanitization
+
+- Never trust user input. Use parameterized queries (ORMs, prepared statements).
+- Sanitize output with DOMPurify or equivalent. Never `innerHTML = userInput`.
+- Validate with schema libraries (Zod, Joi) at API boundaries.
+
+---
+
+## Security Headers
+
+Use `helmet()` middleware or set manually: `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Strict-Transport-Security` (includeSubDomains), `Content-Security-Policy: default-src 'self'`.
+
+---
+
+## Secrets Management
+
+- Never commit secrets. Use environment variables or secret managers (AWS Secrets Manager, HashiCorp Vault).
+- `.env.example` with placeholder keys, `.env` in `.gitignore`.
+- Rotate secrets on schedule (90d max) and immediately on compromise.
+
+---
+
+## Zero Trust Principles
+
+Apply: never trust/always verify, least privilege (RBAC/ABAC), assume breach (encrypt + segment), micro-segmentation (mTLS between services), continuous validation (short TTL sessions, step-up auth), device trust (compliance checks).
+
+---
+
+## OAuth 2.0 / OpenID Connect — Flow Selection
+
+| Client Type | Flow |
+|:---|:---|
+| SPA | Authorization Code + PKCE |
+| Server web app | Authorization Code |
+| Mobile / Desktop | Authorization Code + PKCE |
+| Machine-to-Machine | Client Credentials |
+| Legacy (avoid) | Implicit (deprecated) |
+
+**Token storage**: Never localStorage (XSS). Refresh tokens in httpOnly/Secure/SameSite cookies. Access tokens in memory. All public clients MUST use PKCE (RFC 7636).
+
+---
+
+## API Security
+
+**Rate limiting**: Per-endpoint (expensive ops), per-user (fair usage), sliding window, token bucket, IP-based (unauthenticated). Use `express-rate-limit` or equivalent.
+
+**API keys**: Rotate 90d max, scope to endpoints/methods/IPs, never in client code, separate per environment, log usage.
+
+**Request signing**: HMAC-SHA256 with timestamp to prevent tampering and replay.
+
+**Versioning**: Deprecate old versions lacking security controls. Same auth on all versions.
+
+---
+
+## Supply Chain Security
+
+- `npm audit --audit-level=high` on every CI build
+- Always commit lockfiles; use `npm ci` in CI
+- Review lockfile diffs in PRs
+- Pin exact versions in production (no `^` or `~`)
+- Use Dependabot/Renovate for controlled updates
+- Verify package publisher/download counts before installing
+- Guard against typosquatting (character swaps, hyphen confusion, scope squatting)
+- Consider Socket.dev or Snyk for malicious package detection
+
+---
+
+## Quick Reference
+
+| Practice | Implementation |
+|:---------|:-------------|
+| Passwords | bcrypt/Argon2 |
+| Tokens | Short-lived JWT + refresh |
+| SQL | Parameterized queries |
+| XSS | Sanitize + CSP |
+| HTTPS | TLS 1.3, HSTS |
+| Secrets | Env vars, vaults |
+| Dependencies | npm audit, pin, Snyk |
+| Logging | Audit trail, no PII |
+| Zero Trust | Verify every request |
+| OAuth 2.0 | Auth Code + PKCE |
+| API Keys | Scoped, rotated, logged |
+| Supply Chain | Lockfile, pin, audit |

package/.agent/skills/shell-conventions/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: shell-conventions
+description: PowerShell shell conventions for Windows. Avoid bash-isms. Reference before running terminal commands.
+triggers: [powershell, terminal, shell, command, run, windows, cli]
+---
+
+# Shell Conventions — Windows PowerShell 5.x
+
+> **Environment**: Windows PowerShell 5.x (NOT PowerShell 7/Core)
+> **Scope**: All `run_command` tool calls across all workspaces
+
+---
+
+## 🔴 CRITICAL RULES
+
+1. **NEVER use `&&`** — It is NOT a valid operator in PowerShell 5.x
+2. **NEVER use `cd dir && command`** — Use the `Cwd` parameter on `run_command` instead
+3. **NEVER use `||`** as bash-style OR — Use `if (-not $?) { ... }` instead
+
+---
+
+## Operator Reference
+
+| Operator | Bash                       | PowerShell 5.x          | Notes                             |
+| -------- | -------------------------- | ----------------------- | --------------------------------- |
+| `&&`     | Sequential (conditional)   | ❌ **NOT SUPPORTED**    | Use `;` or `Cwd` param            |
+| `;`      | Sequential (unconditional) | ✅ Sequential execution | Runs next regardless of exit code |
+| `\|`     | Pipe stdout                | ✅ Pipe objects         | Different semantics than bash     |
+| `\|\|`   | OR (run on failure)        | ❌ **NOT SUPPORTED**    | Use `if (-not $?) { ... }`        |
+| `>`      | Redirect stdout            | ✅ Redirect output      | Same behavior                     |
+| `2>&1`   | Redirect stderr to stdout  | ✅ Merge streams        | Same behavior                     |
+
+---
+
+## Patterns
+
+### ❌ WRONG: Chaining with &&
+
+```bash
+cd src && npm test && npm run build
+```
+
+### ✅ RIGHT: Use Cwd parameter
+
+```powershell
+# Set Cwd to "src" on run_command, then just run:
+npm test
+```
+
+### ✅ RIGHT: Sequential with ;
+
+```powershell
+git status; git log --oneline -5
+```
+
+### ✅ RIGHT: Call operator for executables with spaces/special chars
+
+```powershell
+& ".venv\Scripts\ruff.exe" check app/
+& ".venv\Scripts\pytest.exe" tests/ -v
+```
+
+---
+
+## Common Patterns
+
+| Task                | PowerShell Command                          |
+| ------------------- | ------------------------------------------- |
+| Run Node.js tests   | `npm test`                                  |
+| Run Python tests    | `& ".venv\Scripts\pytest.exe" tests/ -q`    |
+| Run linter          | `npm run lint`                              |
+| Check git status    | `git status`                                |
+| Build project       | `npm run build`                             |
+| Install deps        | `npm install`                               |
+| List files          | `Get-ChildItem -Recurse`                    |
+| Find in files       | `Select-String -Pattern "text" -Path "*.md"`|
+
+---
+
+## Virtual Environment (Python)
+
+```powershell
+# Activate (PowerShell)
+& ".venv\Scripts\Activate.ps1"
+
+# Run without activation (preferred for tool calls)
+& ".venv\Scripts\python.exe" -m pytest tests/ -q
+& ".venv\Scripts\python.exe" -m ruff check app/
+```
+
+> [!TIP]
+> For `run_command` tool calls, prefer calling the executable directly with `&` rather than activating the virtual environment.

package/.agent/skills/strategic-compact/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: strategic-compact
+description: Context window management with strategic compaction
+triggers: [context-warning, manual]
+---
+
+# Strategic Compact Skill
+
+> **Purpose**: Manage context window efficiently while preserving important information
+
+---
+
+## Overview
+
+As conversations grow, context window limits require strategic compaction. This skill ensures important context is preserved while freeing space for new work.
+
+---
+
+## Workflow
+
+### 1. Assess Context
+
+Evaluate current context usage:
+
+- How much context is used?
+- What is the oldest content?
+- What is most important?
+
+### 2. Prioritize
+
+Rank content by importance:
+
+| Priority | Content Type               |
+| :------- | :------------------------- |
+| CRITICAL | Active code being modified |
+| HIGH     | Current task context       |
+| MEDIUM   | Related code for reference |
+| LOW      | Completed discussions      |
+
+### 3. Compact
+
+Summarize or remove low-priority content:
+
+- Summarize completed tasks
+- Remove verbose output
+- Keep code snippets, remove explanations
+
+### 4. Persist
+
+Save important context externally:
+
+- Update `session-state.json`
+- Document decisions in `decisions/`
+- Create checkpoints
+
+---
+
+## Integration
+
+- Triggered at context warning threshold
+- Can be invoked with `/compact`
+- Preserves session continuity