feat(development/pi-coding-agent): added the submodule, CONTEXT.md and prompts

12 files changed, 359 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..1b27012
--- /dev/null
+++ b/modules/development/pi-coding-agent/default.nix
@@ -0,0 +1,112 @@
+{
+  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;
+      default = pkgs.pi;
+      description = "The Pi Coding Agent package to use.";
+    };
+  };
+
+  config = lib.mkIf cfg.enable {
+    home.sessionVariables = {
+      PI_CODING_AGENT_DIR = configDir;
+    };
+
+    home.file = {
+      "${configDir}/skills".source = ./skills;
+      "${configDir}/prompts".source = ./prompts;
+      "${configDir}/agents".source = ./agents;
+    };
+
+    programs.pi-coding-agent = {
+      enable = true;
+      inherit 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 = 3;
+          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 = with pkgs; [
+        nodejs
+        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/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;