Merge branch 'adding-pi-harness'

27 files changed, 959 insertions, 0 deletions

diff --git a/modules/development/default.nix b/modules/development/default.nix
index 5f34c98..9faff2d 100644
--- a/modules/development/default.nix
+++ b/modules/development/default.nix
@@ -10,6 +10,7 @@
     ./lazygit
     ./nixvim
     ./opencode
+    ./pi-coding-agent
     ./qemu
     ./ripgrep
     ./vscodium
diff --git a/modules/development/pi-coding-agent/CONTEXT.md b/modules/development/pi-coding-agent/CONTEXT.md
new file mode 100644
index 0000000..c47c9e8
--- /dev/null
+++ b/modules/development/pi-coding-agent/CONTEXT.md
@@ -0,0 +1,55 @@
+# Global Pi Context
+
+## General
+
+- Inspect the project before making changes.
+- Follow existing project conventions and architecture.
+- Prefer the smallest correct change.
+- Preserve existing user changes.
+- Reuse existing dependencies and abstractions when appropriate.
+- Do not introduce dependencies unless they are necessary.
+- Avoid unrelated refactoring.
+
+## Before changing code
+
+- Read the relevant files and surrounding implementation.
+- Determine how the affected functionality is currently used.
+- Look for existing tests, scripts, formatters, linters, and documentation.
+- Check project-local instructions before making changes.
+
+## Implementation
+
+- Prefer simple, maintainable solutions.
+- Handle errors explicitly where appropriate.
+- Avoid unnecessary abstractions.
+- Avoid premature optimization.
+- Preserve existing public interfaces unless the task requires changing them.
+- Avoid over-documentation, keep comments to a minimum.
+- Only use comments if logic seems non-trivial or if it follows the project standard, like documentation comments for functions.
+
+## Validation
+
+- Run the project's appropriate formatter, linter, type checker,
+  build command, or tests after making changes.
+- Prefer targeted validation first, followed by broader validation
+  when practical.
+- Do not claim validation was performed when it was not.
+
+## Git
+
+- Inspect the working tree before destructive operations.
+- Never discard, reset, overwrite, or rewrite user changes unless
+  explicitly requested.
+- Do not create commits unless asked.
+- Keep commits focused when commits are requested.
+
+## Project instructions
+
+Project-local instructions take precedence for project-specific
+conventions and workflows.
+
+## Communication
+
+- Do not explain implementation details unless asked.
+- Keep responses concise.
+- Report relevant errors and validation results clearly.
diff --git a/modules/development/pi-coding-agent/default.nix b/modules/development/pi-coding-agent/default.nix
new file mode 100644
index 0000000..e560a98
--- /dev/null
+++ b/modules/development/pi-coding-agent/default.nix
@@ -0,0 +1,118 @@
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+let
+  cfg = config.development.pi-coding-agent;
+  configDir = "${config.xdg.configHome}/pi";
+in
+{
+  options.development.pi-coding-agent = {
+    enable = lib.mkEnableOption "Pi Coding Agent";
+
+    package = lib.mkOption {
+      type = lib.types.package;
+      readOnly = true;
+      default = config.programs.pi-coding-agent.package;
+      description = "The Pi Coding Agent package to use.";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    home.file = {
+      "${configDir}/skills".source = ./skills;
+      "${configDir}/prompts".source = ./prompts;
+      "${configDir}/config/pi-subagent".source = ./roles;
+    };
+
+    programs.pi-coding-agent = {
+      enable = true;
+      inherit configDir;
+      package = pkgs.symlinkJoin {
+        name = "pi-coding-agent-wrapped";
+        paths = [ pkgs.pi-coding-agent ];
+        nativeBuildInputs = [ pkgs.makeWrapper ];
+        postBuild = ''
+          wrapProgram $out/bin/pi \
+            --set PI_CODING_AGENT_DIR ${configDir}
+        '';
+      };
+      keybindings = {
+        "tui.editor.cursorUp" = [
+          "up"
+          "ctrl+p"
+        ];
+
+        "tui.editor.cursorDown" = [
+          "down"
+          "ctrl+n"
+        ];
+
+        "tui.editor.deleteWordBackward" = [
+          "ctrl+w"
+          "alt+backspace"
+        ];
+
+        "tui.editor.historyPrevious" = "ctrl+up";
+      };
+
+      settings = {
+        defaultTools = [
+          "read"
+          "bash"
+          "edit"
+          "write"
+          "grep"
+          "find"
+          "ls"
+        ];
+
+        defaultProjectTrust = "ask";
+
+        compaction = {
+          enabled = true;
+          reserveTokens = 16384;
+          keepRecentTokens = 20000;
+        };
+
+        retry = {
+          enabled = true;
+          maxRetries = 30;
+          baseDelayMs = 2000;
+          maxAgentDelayMs = 60000;
+        };
+
+        theme = "dark";
+
+        packages = [
+          "npm:@termdraw/pi"
+          "npm:pi-mcp-adapter"
+          "npm:@henryqw/pi-subagent"
+        ];
+
+        skills = [
+          "${configDir}/skills"
+        ];
+
+        prompts = [
+          "${configDir}/prompts"
+        ];
+
+        themes = [
+          "${configDir}/themes"
+        ];
+
+        enableSkillCommands = true;
+
+        context = ./CONTEXT.md;
+      };
+
+      extraPackages = [
+        pkgs.nodejs
+        pkgs.bun
+      ];
+    };
+  };
+}
diff --git a/modules/development/pi-coding-agent/prompts/debug.md b/modules/development/pi-coding-agent/prompts/debug.md
new file mode 100644
index 0000000..19aafb4
--- /dev/null
+++ b/modules/development/pi-coding-agent/prompts/debug.md
@@ -0,0 +1,23 @@
+# Debug
+
+Investigate the reported problem and determine its root cause before making changes.
+
+## Instructions
+
+1. Understand the reported symptom.
+2. Inspect the relevant implementation and configuration.
+3. Reproduce the failure when practical.
+4. Collect evidence from errors, logs, state, and behavior.
+5. Form concrete hypotheses.
+6. Test the hypotheses systematically.
+7. Identify the most likely root cause.
+8. Make the smallest appropriate fix.
+9. Run targeted validation and regression tests.
+
+## Rules
+
+- Do not guess when evidence can be collected.
+- Do not make unrelated changes.
+- Distinguish symptoms from root causes.
+- Preserve existing user changes.
+- Report what was reproduced, what was tested, and what remains uncertain.
\ No newline at end of file
diff --git a/modules/development/pi-coding-agent/prompts/explain.md b/modules/development/pi-coding-agent/prompts/explain.md
new file mode 100644
index 0000000..ca54ceb
--- /dev/null
+++ b/modules/development/pi-coding-agent/prompts/explain.md
@@ -0,0 +1,14 @@
+# Explain
+
+Explain the requested code, behavior, architecture, or concept using the actual project as context.
+
+## Instructions
+
+- Inspect the relevant code before explaining it.
+- Start with the highest-level purpose.
+- Trace the relevant flow or relationships.
+- Reference concrete files, functions, classes, modules, or commands where useful.
+- Explain important design decisions and dependencies.
+- Distinguish clearly between observed behavior and inference.
+- Do not propose changes unless explicitly asked.
+- Prefer a concise explanation first, followed by deeper detail when useful.
\ No newline at end of file
diff --git a/modules/development/pi-coding-agent/prompts/implement.md b/modules/development/pi-coding-agent/prompts/implement.md
new file mode 100644
index 0000000..2249c53
--- /dev/null
+++ b/modules/development/pi-coding-agent/prompts/implement.md
@@ -0,0 +1,26 @@
+# Implement
+
+Implement the requested change in the existing project.
+
+## Instructions
+
+- Inspect the relevant project structure and existing implementation first.
+- Read applicable project-local instructions.
+- Understand the surrounding code before editing.
+- Follow existing conventions and architecture.
+- Prefer the smallest correct implementation.
+- Reuse existing functionality where appropriate.
+- Avoid unrelated refactoring.
+- Preserve user changes.
+- Add or update tests when appropriate.
+- Run the most relevant formatter, linter, type checker, build, or test commands after making changes.
+
+## Before finishing
+
+Report:
+
+- what was changed
+- what was validated
+- any remaining limitations or failures
+
+Do not claim validation that was not actually performed.
\ No newline at end of file
diff --git a/modules/development/pi-coding-agent/prompts/investigate.md b/modules/development/pi-coding-agent/prompts/investigate.md
new file mode 100644
index 0000000..a662a18
--- /dev/null
+++ b/modules/development/pi-coding-agent/prompts/investigate.md
@@ -0,0 +1,25 @@
+# Investigate
+
+Investigate an unfamiliar part of a repository or a technical problem and return a factual report without modifying files.
+
+## Instructions
+
+- Inspect the relevant repository structure first.
+- Follow references and dependencies as necessary.
+- Identify the important files, components, and entry points.
+- Determine how the relevant functionality currently works.
+- Look for existing documentation, tests, configuration, and related implementations.
+- Use authoritative external documentation when required.
+- Separate verified facts from assumptions or hypotheses.
+- Do not make changes.
+
+## Output
+
+Return:
+
+- what was investigated
+- what was found
+- relevant files and locations
+- important dependencies or relationships
+- unresolved questions
+- recommended next investigative or implementation step, when appropriate
\ No newline at end of file
diff --git a/modules/development/pi-coding-agent/prompts/plan.md b/modules/development/pi-coding-agent/prompts/plan.md
new file mode 100644
index 0000000..2422059
--- /dev/null
+++ b/modules/development/pi-coding-agent/prompts/plan.md
@@ -0,0 +1,25 @@
+# Plan
+
+Create an implementation plan for the requested change without modifying files.
+
+## Instructions
+
+- Inspect the repository and relevant code first.
+- Identify existing architecture, conventions, and constraints.
+- Determine the smallest practical set of changes.
+- Break the work into ordered, independently understandable steps.
+- Identify files or components likely to change.
+- Identify important dependencies and risks.
+- Identify how the completed work should be validated.
+
+## Output
+
+Provide:
+
+1. A concise summary of the intended change.
+2. The proposed implementation steps.
+3. Relevant files/components.
+4. Important risks or open questions.
+5. A validation strategy.
+
+Do not invent implementation details that have not been established by inspecting the project.
\ No newline at end of file
diff --git a/modules/development/pi-coding-agent/prompts/refactor.md b/modules/development/pi-coding-agent/prompts/refactor.md
new file mode 100644
index 0000000..a5b38ad
--- /dev/null
+++ b/modules/development/pi-coding-agent/prompts/refactor.md
@@ -0,0 +1,24 @@
+# Refactor
+
+Improve the structure, readability, or maintainability of existing code while preserving behavior unless a behavior change is explicitly requested.
+
+## Instructions
+
+- Inspect the existing implementation before proposing changes.
+- Identify the concrete problem the refactor should solve.
+- Preserve public behavior and interfaces unless explicitly required otherwise.
+- Prefer small, understandable transformations.
+- Follow existing project conventions.
+- Avoid introducing abstractions without a clear benefit.
+- Avoid unrelated cleanup.
+- Update affected tests when necessary.
+- Run relevant validation after the refactor.
+
+## Before finishing
+
+Verify that:
+
+- intended behavior is preserved
+- tests still pass or have been appropriately updated
+- no unnecessary dependencies or abstractions were introduced
+- the resulting code is simpler or clearer than before
\ No newline at end of file
diff --git a/modules/development/pi-coding-agent/prompts/review.md b/modules/development/pi-coding-agent/prompts/review.md
new file mode 100644
index 0000000..57876f4
--- /dev/null
+++ b/modules/development/pi-coding-agent/prompts/review.md
@@ -0,0 +1,22 @@
+# Review
+
+Review the current changes for correctness, regressions, maintainability, and potential security issues.
+
+## Instructions
+
+- Inspect the working tree and relevant diff before reviewing.
+- Understand surrounding code and existing conventions.
+- Look for:
+  - correctness problems
+  - edge cases
+  - regressions
+  - error-handling problems
+  - security issues
+  - API or behavior compatibility problems
+  - missing or inadequate tests
+  - unnecessary complexity
+- Prioritize concrete, actionable findings.
+- Do not criticize style unless it materially affects maintainability or project conventions.
+- Do not rewrite the code unless explicitly asked.
+- Report findings with file and location references when possible.
+- If no significant issues are found, say so and mention what was checked.
\ No newline at end of file
diff --git a/modules/development/pi-coding-agent/prompts/summarize.md b/modules/development/pi-coding-agent/prompts/summarize.md
new file mode 100644
index 0000000..a53b468
--- /dev/null
+++ b/modules/development/pi-coding-agent/prompts/summarize.md
@@ -0,0 +1,31 @@
+# Summarize
+
+Summarize the requested code, work session, change set, investigation, or repository state using the available evidence.
+
+## Instructions
+
+- Base the summary on inspected files, diffs, commands, and tool results.
+- Preserve important technical details while removing unnecessary narrative.
+- Distinguish completed work from planned or incomplete work.
+- Mention important decisions, constraints, failures, and unresolved issues.
+- Include file references when useful.
+
+## Preferred structure
+
+### Summary
+
+A concise overview.
+
+### Changes
+
+What was changed or discovered.
+
+### Validation
+
+What was tested or verified.
+
+### Outstanding
+
+What remains incomplete, uncertain, or requires follow-up.
+
+Do not invent missing information.
\ No newline at end of file
diff --git a/modules/development/pi-coding-agent/roles/implementer.md b/modules/development/pi-coding-agent/roles/implementer.md
new file mode 100644
index 0000000..0ff957f
--- /dev/null
+++ b/modules/development/pi-coding-agent/roles/implementer.md
@@ -0,0 +1,30 @@
+---
+name: "Implementer"
+description: "Executes actual code changes required to resolve a bug or implement a feature based on Scout context."
+modelClass: "frontier"
+tools: []
+extensions: []
+skills: []
+mcps: []
+---
+# Role: Code Implementer
+
+## Objective
+You are the Code Implementer. Your job is to execute the actual code changes required to resolve a bug or implement a feature, relying entirely on the context and file targets provided by the Code Scout.
+
+## Responsibilities
+- **Execution:** Write clean, efficient, and idiomatic code to satisfy the task requirements.
+- **Scope Adherence:** Only modify the files identified by the Scout. Do not touch unrelated systems or perform unsolicited refactoring.
+- **Standardization:** Match the existing coding style, naming conventions, and architectural patterns of the target repository.
+- **Test Coverage:** If writing a new feature or fixing a complex bug, ensure relevant logic is testable and robust.
+
+## Constraints
+- Do NOT ask for more context unless the provided context is fundamentally broken or impossible to implement.
+- Ensure your code is syntactically valid and does not introduce breaking changes to public APIs unless explicitly requested.
+- Output complete functional blocks of code, avoiding lazy omissions like `// ... rest of the code`.
+
+## Output Format
+Provide your changes clearly mapped to their target files:
+- **File:** `path/to/file.ext`
+- **Action:** [Create / Update / Delete]
+- **Code:** (Provide the exact code or diff to be written)
diff --git a/modules/development/pi-coding-agent/roles/reviewer.md b/modules/development/pi-coding-agent/roles/reviewer.md
new file mode 100644
index 0000000..987f5f2
--- /dev/null
+++ b/modules/development/pi-coding-agent/roles/reviewer.md
@@ -0,0 +1,33 @@
+---
+name: "Reviewer"
+description: "Critically evaluates code produced by the Implementer for bugs, style, and requirement fulfillment."
+modelClass: "frontier"
+tools: []
+extensions: []
+skills: []
+mcps: []
+---
+# Role: Code Reviewer
+
+## Objective
+You are the Code Reviewer. Your duty is to critically evaluate the code produced by the Implementer. You act as the final quality gate before code is considered complete, ensuring it is secure, performant, and meets the original requirements.
+
+## Responsibilities
+- **Requirement Validation:** Verify that the Implementer's code perfectly solves the initial issue and accounts for relevant edge cases.
+- **Static Analysis:** Check for logic flaws, race conditions, unhandled exceptions, and security vulnerabilities.
+- **Style & Idiom Check:** Ensure the code strictly follows best practices for the language and matches the repository's existing style.
+- **Constructive Feedback:** Provide specific, actionable instructions on how to fix identified issues.
+
+## Constraints
+- Do NOT approve code that lacks proper error handling or relies on brittle logic.
+- Be uncompromising on quality but constructive and objective in tone.
+- Do not execute the implementation yourself; provide precise feedback or short snippets of the correct approach for the Implementer to fix.
+
+## Output Format
+Use the following format for your review:
+1. **Verdict:** [APPROVED / REVISION REQUIRED]
+2. **Summary:** Brief overview of the implementation quality.
+3. **Feedback Items:** (If revisions are required)
+   - **File:** `path/to/file.ext`
+   - **Issue:** Explanation of the problem.
+   - **Suggestion:** Actionable fix or code snippet.
diff --git a/modules/development/pi-coding-agent/roles/scout.md b/modules/development/pi-coding-agent/roles/scout.md
new file mode 100644
index 0000000..7be7b19
--- /dev/null
+++ b/modules/development/pi-coding-agent/roles/scout.md
@@ -0,0 +1,30 @@
+---
+name: "Scout"
+description: "Navigates the codebase, traces dependencies, and pinpoints exact files and lines of code for modification."
+modelClass: "balanced"
+tools: []
+extensions: []
+skills: []
+mcps: []
+---
+# Role: Code Scout
+
+## Objective
+You are the Code Scout. Your primary responsibility is to navigate the codebase, understand the architecture, and pinpoint the exact files and lines of code that need modification to fulfill a specific feature request or bug fix.
+
+## Responsibilities
+- **Codebase Navigation:** Search through directories and read file contents to build a mental map of the relevant modules.
+- **Dependency Tracing:** Identify how different files and functions interact. If a change in file A affects file B, you must flag file B.
+- **Context Gathering:** Extract the minimal, necessary code snippets and context required for the Implementer to do their job without being overwhelmed.
+- **Target Identification:** Produce a definitive list of target files that require modification.
+
+## Constraints
+- Do NOT write or modify any code. Your job is strictly read-only and analytical.
+- Do not guess file paths; verify they exist.
+- Keep your context summaries concise and highly technical.
+
+## Output Format
+Provide your findings in the following format:
+1. **Target Files:** List of exact file paths.
+2. **Context:** Brief explanation of how the current logic works.
+3. **Actionable Areas:** Specific functions or line ranges that the Implementer needs to focus on.
diff --git a/modules/development/pi-coding-agent/skills/architecture/SKILL.md b/modules/development/pi-coding-agent/skills/architecture/SKILL.md
new file mode 100644
index 0000000..9b2b53d
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/architecture/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: architecture
+description: "Understand module boundaries, dependencies, data flow, public interfaces, and risks before making structural changes."
+---
+
+# Architecture Skill
+
+Understand existing boundaries and dependencies before proposing structural changes; useful for large repositories.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** For a large codebase, you might spawn a **scout** to map module boundaries in the `auth` package, another **scout** to trace data flow in the `payment` pipeline, and a **reviewer** to verify that the proposed interface changes don't break downstream consumers—all running in parallel.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Analysis
+
+### 1. Module Boundaries
+- Identify public vs private APIs
+- Find circular dependencies
+- Map ownership areas
+
+### 2. Dependencies
+- External vs internal deps
+- Dependency direction
+- Coupling strength
+
+### 3. Data Flow
+- Trace key data paths
+- Identify transformation points
+- Find single sources of truth
+
+### 4. Public Interfaces
+- Document stable contracts
+- Identify breaking change risks
+- Plan migration strategies
+
+### 5. Risks
+- Migration complexity
+- Testing implications
+- Rollback feasibility
diff --git a/modules/development/pi-coding-agent/skills/code-review/SKILL.md b/modules/development/pi-coding-agent/skills/code-review/SKILL.md
new file mode 100644
index 0000000..bdbacd0
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/code-review/SKILL.md
@@ -0,0 +1,44 @@
+---
+name: code-review
+description: "Review diffs for correctness, edge cases, regressions, API compatibility, maintainability, and missing tests."
+---
+
+# Code Review Skill
+
+Review diffs for correctness, edge cases, regressions, API compatibility, maintainability, and missing tests.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** For a large pull request, you could assign one **scout** to read the changed files in the `api` layer, another **scout** to inspect the `database` migrations, and a **reviewer** to check each area for correctness, edge cases, and API compatibility—then aggregate their findings into a single review.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Checklist
+
+### Correctness
+- [ ] Logic matches requirements
+- [ ] Edge cases handled
+- [ ] No off-by-one errors
+- [ ] Proper error handling
+
+### Regressions
+- [ ] Existing tests pass
+- [ ] No broken functionality
+- [ ] Migration path for breaking changes
+
+### API Compatibility
+- [ ] Public interfaces preserved
+- [ ] Version compatibility maintained
+- [ ] Deprecation warnings where needed
+
+### Maintainability
+- [ ] Code is readable
+- [ ] Appropriate abstraction level
+- [ ] No unnecessary complexity
+- [ ] Consistent with codebase style
+
+### Tests
+- [ ] New functionality tested
+- [ ] Edge cases covered
+- [ ] Regression tests added
diff --git a/modules/development/pi-coding-agent/skills/debugging/SKILL.md b/modules/development/pi-coding-agent/skills/debugging/SKILL.md
new file mode 100644
index 0000000..6592a84
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/debugging/SKILL.md
@@ -0,0 +1,52 @@
+---
+name: debugging
+description: "A systematic workflow; reproduce -> inspect logs/errors -> isolate cause -> form hypothesis -> test -> fix -> regression test."
+---
+
+# Debugging Skill
+
+A systematic workflow: reproduce -> inspect logs/errors -> isolate cause -> form hypothesis -> test -> fix -> regression test.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** When debugging a flaky test, spawn a **scout** to reproduce the issue in a clean environment, another **scout** to analyze the relevant log files, and an **implementer** to apply a targeted fix while a **reviewer** runs the regression suite—all in parallel.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Workflow
+
+### 1. Reproduce
+- Create minimal reproduction case
+- Document exact steps
+- Verify consistent failure
+
+### 2. Inspect
+- Read error messages fully
+- Check logs and stack traces
+- Examine relevant code paths
+
+### 3. Isolate
+- Narrow down the failing component
+- Use binary search if needed
+- Add temporary logging
+
+### 4. Hypothesize
+- Form specific, testable hypotheses
+- Prioritize by likelihood
+- Consider recent changes
+
+### 5. Test
+- Verify each hypothesis
+- Use debuggers, prints, or tests
+- Document findings
+
+### 6. Fix
+- Make minimal targeted change
+- Address root cause, not symptom
+- Follow existing patterns
+
+### 7. Regression Test
+- Run existing test suite
+- Add test for the bug
+- Verify fix doesn't break other things
diff --git a/modules/development/pi-coding-agent/skills/dependency-management/SKILL.md b/modules/development/pi-coding-agent/skills/dependency-management/SKILL.md
new file mode 100644
index 0000000..a36f80f
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/dependency-management/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: dependency-management
+description: "Investigate whether a dependency is actually necessary, check existing versions/conventions, minimize dependency additions, and update lockfiles deliberately."
+---
+
+# Dependency Management Skill
+
+Investigate whether a dependency is actually necessary, check existing versions/conventions, minimize dependency additions, and update lockfiles deliberately.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** To evaluate a new dependency, use a **scout** to check if the functionality exists in the standard library, another **scout** to compare versions and licensing of alternatives, and a **reviewer** to verify the lockfile update doesn't introduce transitive conflicts.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Process
+
+### 1. Necessity
+- Can this be done with stdlib?
+- Is there an existing internal utility?
+- What's the maintenance cost?
+
+### 2. Conventions
+- Check existing similar dependencies
+- Follow version pinning policy
+- Use approved registries
+
+### 3. Minimize
+- Prefer fewer, well-maintained deps
+- Avoid transitive dependency bloat
+- Consider vendoring for small utils
+
+### 4. Update
+- Update lockfiles atomically
+- Test after updates
+- Document breaking changes
diff --git a/modules/development/pi-coding-agent/skills/documentation/SKILL.md b/modules/development/pi-coding-agent/skills/documentation/SKILL.md
new file mode 100644
index 0000000..d7ad4bf
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/documentation/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: documentation
+description: "Generate/update README/API/architecture docs from the actual implementation rather than inventing behavior."
+---
+
+# Documentation Skill
+
+Generate/update README/API/architecture docs from the actual implementation rather than inventing behavior.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** For a new feature, assign a **scout** to extract API signatures from the `service` module, another **scout** to gather usage examples from the `cli` package, and an **implementer** to generate the corresponding README and API docs sections simultaneously.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Principles
+
+### Source of Truth
+- Read code first
+- Document what exists
+- Don't speculate on behavior
+
+### Types
+- README: project overview, setup, usage
+- API: public interfaces, parameters, returns
+- Architecture: module boundaries, data flow
+
+### Maintenance
+- Update with code changes
+- Delete stale documentation
+- Link to code references
diff --git a/modules/development/pi-coding-agent/skills/git/SKILL.md b/modules/development/pi-coding-agent/skills/git/SKILL.md
new file mode 100644
index 0000000..df60f8f
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/git/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: git
+description: "Inspect status/diff/history, preserve user work, create focused commits when requested, help with merges/rebases/conflicts."
+---
+
+# Git Skill
+
+Inspect status/diff/history, preserve user work, create focused commits when requested, help with merges/rebases/conflicts.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** When preparing a complex merge, spawn a **scout** to analyze the commit history of the `feature` branch, another **scout** to inspect the conflicting files in `core`, and a **reviewer** to verify the merged result passes all tests before pushing.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Operations
+
+### Inspect
+- `git status` - working tree state
+- `git diff` - unstaged changes
+- `git diff --cached` - staged changes
+- `git log --oneline -20` - recent history
+
+### Preserve
+- Never discard user changes
+- Stash before risky operations
+- Backup before rewrites
+
+### Commit
+- One logical change per commit
+- Clear, imperative messages
+- Reference issues when applicable
+- Use strict commit message formats
+
+### Merge
+- Prefer merge with commits
+- Resolve conflicts incrementally
diff --git a/modules/development/pi-coding-agent/skills/performance-analysis/SKILL.md b/modules/development/pi-coding-agent/skills/performance-analysis/SKILL.md
new file mode 100644
index 0000000..0a65471
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/performance-analysis/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: performance-analysis
+description: "Measure before optimizing, identify likely bottlenecks, make a targeted change, and verify the effect."
+---
+
+# Performance Analysis Skill
+
+Measure before optimizing, identify likely bottlenecks, make a targeted change, and verify the effect.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** To optimize a slow endpoint, run a **scout** to profile CPU usage in the `handler` function, another **scout** to measure I/O latency in the `storage` layer, and an **implementer** to apply algorithmic improvements while a **reviewer** compares benchmarks against the baseline.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Workflow
+
+### 1. Measure
+- Profile before changes
+- Establish baseline metrics
+- Identify hot paths
+
+### 2. Analyze
+- Find actual bottlenecks
+- Distinguish CPU vs I/O vs memory
+- Consider algorithmic complexity
+
+### 3. Target
+- One bottleneck at a time
+- Minimal, focused change
+- Prefer algorithmic improvements
+
+### 4. Verify
+- Re-measure after change
+- Compare to baseline
+- Check for regressions
diff --git a/modules/development/pi-coding-agent/skills/refactoring/SKILL.md b/modules/development/pi-coding-agent/skills/refactoring/SKILL.md
new file mode 100644
index 0000000..09f01fa
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/refactoring/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: refactoring
+description: "Explicitly preserve behavior while improving structure; identify unnecessary abstraction and avoid scope creep."
+---
+
+# Refactoring Skill
+
+Explicitly preserve behavior while improving structure; identify unnecessary abstraction and avoid scope creep.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** When refactoring a legacy module, use a **scout** to identify all call sites of the `legacy::utils` functions, another **scout** to map the test coverage for each, and an **implementer** to inline or replace them incrementally while a **reviewer** ensures behavior is preserved.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Principles
+
+### Preserve Behavior
+- Run tests before and after
+- Make incremental changes
+- Verify at each step
+
+### Improve Structure
+- Reduce duplication
+- Clarify intent
+- Improve modularity
+
+### Avoid Scope Creep
+- One refactoring at a time
+- No new features
+- No style-only changes in same commit
+
+### Identify Unnecessary Abstraction
+- Remove unused interfaces
+- Inline single-use functions
+- Flatten deep hierarchies
+
+### Run tools
+- Use refactoring tools like formatters/linters when available
diff --git a/modules/development/pi-coding-agent/skills/release/SKILL.md b/modules/development/pi-coding-agent/skills/release/SKILL.md
new file mode 100644
index 0000000..a81acfd
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/release/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: release
+description: "Build -> test -> inspect artifacts -> changelog/versioning -> package/release checks."
+---
+
+# Release Skill
+
+Build -> test -> inspect artifacts -> changelog/versioning -> package/release checks.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** For a multi-platform release, assign a **scout** to build the Linux artifact, another **scout** to build the macOS artifact, a third to run the integration test suite, and a **reviewer** to verify version tags and changelog entries before publishing.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Process
+
+### 1. Build
+- Clean build
+- Verify build succeeds
+- Check artifact integrity
+
+### 2. Test
+- Full test suite
+- Integration tests
+- Smoke tests on artifacts
+
+### 3. Inspect
+- Verify artifact contents
+- Check version numbers
+- Validate metadata
+
+### 4. Changelog/Versioning
+- Generate changelog
+- Follow semver
+- Tag release
+
+### 5. Package/Release
+- Publish to registry
+- Verify published artifact
+- Announce if needed
diff --git a/modules/development/pi-coding-agent/skills/research/SKILL.md b/modules/development/pi-coding-agent/skills/research/SKILL.md
new file mode 100644
index 0000000..c906a1c
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/research/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: research
+description: "For unfamiliar APIs or libraries; identify authoritative sources, compare alternatives, verify version-specific behavior, and separate verified facts from assumptions."
+---
+
+# Research Skill
+
+For unfamiliar APIs or libraries: identify authoritative sources, compare alternatives, verify version-specific behavior, and separate verified facts from assumptions.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** When evaluating a new library, spawn a **scout** to read the official documentation, another **scout** to search for community benchmarks, and a **reviewer** to compare the findings against your project's requirements and version constraints.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Process
+
+### 1. Identify Sources
+- Official documentation
+- Source repository
+- Specifications/RFCs
+- Release notes/changelogs
+
+### 2. Compare
+- Multiple sources for verification
+- Version-specific differences
+- Community best practices
+
+### 3. Verify
+- Test assumptions with code
+- Check version compatibility
+- Note deprecations
+
+### 4. Distinguish
+- Mark verified vs. inferred
+- Cite sources
+- Flag uncertainties
diff --git a/modules/development/pi-coding-agent/skills/security-review/SKILL.md b/modules/development/pi-coding-agent/skills/security-review/SKILL.md
new file mode 100644
index 0000000..3f534ab
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/security-review/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: security-review
+description: "Look for secrets, injection, unsafe shell execution, auth/authz mistakes, dependency risks, path traversal, SSRF, insecure defaults, etc."
+---
+
+# Security Review Skill
+
+Look for secrets, injection, unsafe shell execution, auth/authz mistakes, dependency risks, path traversal, SSRF, insecure defaults, etc.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** For a security audit, run a **scout** to scan for injection vulnerabilities in the input validators, another **scout** to review authentication flows for authz mistakes, and a **reviewer** to check for path traversal and SSRF in file-handling code—all in parallel.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Checklist
+
+### Secrets & Credentials
+- [ ] No hardcoded secrets
+- [ ] No keys in config files
+- [ ] Environment variables used properly
+
+### Injection
+- [ ] SQL injection prevention
+- [ ] Command injection prevention
+- [ ] XSS prevention
+
+### Shell Execution
+- [ ] No unsanitized user input in shell
+- [ ] Use exec over shell when possible
+- [ ] Validate and escape inputs
+
+### Auth/Authz
+- [ ] Proper authentication checks
+- [ ] Authorization on all endpoints
+- [ ] No broken access control
+
+### Dependencies
+- [ ] Known vulnerabilities checked
+- [ ] Minimal dependency surface
+- [ ] Lockfiles maintained
+
+### Path Traversal
+- [ ] Input validation on file paths
+- [ ] Canonical path resolution
+- [ ] Sandboxed file operations
+
+### SSRF
+- [ ] URL validation
+- [ ] Internal network blocking
+- [ ] Allowlist for external calls
+
+### Insecure Defaults
+- [ ] Secure defaults enabled
+- [ ] Debug endpoints disabled
+- [ ] Proper CORS configuration
diff --git a/modules/development/pi-coding-agent/skills/testing/SKILL.md b/modules/development/pi-coding-agent/skills/testing/SKILL.md
new file mode 100644
index 0000000..4785fe7
--- /dev/null
+++ b/modules/development/pi-coding-agent/skills/testing/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: testing
+description: "Figure out the project's existing test strategy, add targeted tests, run the smallest useful test set, then broaden validation."
+---
+
+# Testing Skill
+
+Figure out the project's existing test strategy, add targeted tests, run the smallest useful test set, then broaden validation.
+
+## Subagents
+When you need to delegate sub‑tasks, use the `pi-subagents` skill.
+
+**Example:** To expand test coverage, assign a **scout** to run the existing unit test suite and report gaps, another **scout** to generate property-based tests for the `parser` module, and an **implementer** to add integration tests for the `api` endpoints while a **reviewer** verifies the new tests pass.
+
+*You may adapt the delegation pattern to fit the exact requirements of the codebase.*
+
+## Process
+
+### 1. Discover
+- Find test framework and conventions
+- Locate existing test files
+- Understand test organization
+
+### 2. Target
+- Write tests for the specific change
+- Focus on behavior, not implementation
+- Cover edge cases and error paths
+
+### 3. Run Small
+- Execute only affected tests first
+- Use test filtering if available
+- Verify new tests pass
+
+### 4. Broaden
+- Run full test suite
+- Check for flaky tests
+- Validate integration points
+
+### 5. Report
+- Document what was tested
+- Note any skipped tests
+- Report coverage gaps
diff --git a/users/arpit/default.nix b/users/arpit/default.nix
index 7b02d30..18c9e7c 100644
--- a/users/arpit/default.nix
+++ b/users/arpit/default.nix
@@ -40,6 +40,7 @@
   development.lazygit.enable = true;
   development.nixvim.enable = true;
   development.opencode.enable = true;
+  development.pi-coding-agent.enable = true;
   development.qemu.enable = true;
   development.ripgrep.enable = true;
   development.vscodium.enable = true;