@sangyaahub/pi-marg 1.0.0

package/skills/auto-mode-router/references/native-pi-runtime.md

@@ -0,0 +1,52 @@
+# Pi runtime integration
+
+Read this reference only when `auto_runtime_status` reports `runtime: Pi`. The shared A/B/C/D contract remains authoritative; optional OMP conveniences do not become imaginary Pi features.
+
+## Execution shape
+
+```text
+A model → discovery record
+   ↓ switch model
+C model → independent plan review
+   ↓ accepted plan
+B model → implementation and tests
+   ↓ switch model
+D model → independent read-only review
+```
+
+Pi can perform this sequentially in one session with `auto_model_route`. Parallel work is allowed only when `task` or another compatible subagent extension is actually detected. Do not simulate a swarm in prose.
+
+## Models
+
+- The Pi adapter uses the session's scoped models when configured; otherwise it uses the authenticated available registry.
+- Activate the saved exact selector before every A/B/C/D stage.
+- If activation fails, stop the stage and ask the user to repair authentication or select another catalog entry.
+- C never edits the plan silently; it returns a verdict and required revisions. D remains read-only.
+
+## Code intelligence
+
+Upstream Pi provides file and shell primitives; LSP, AST, CodeGraph, browser, debugger, and security tools depend on installed extensions or repository commands.
+
+- Use `codegraph_explore` when detected.
+- Otherwise, use an installed CodeGraph CLI through `bash` after `setup-codegraph.sh` has been explicitly applied.
+- If neither exists, use exact repository-native language/compiler tools and label repository-wide impact as not verified.
+- Do not replace architecture analysis with broad grep output.
+
+## Review and verification
+
+- If a `review` command exists, it may host the C/D contract; otherwise run the selected reviewer model sequentially.
+- Every implementation still runs focused tests and the narrowest broader check protecting affected contracts.
+- Use browser, debugger, or security extensions only when `auto_runtime_status` detects them.
+- Record unavailable surfaces as `not verified`, including the practical consequence.
+
+## Context and memory
+
+Pi may provide compaction and session branching, but OMP `checkpoint`/`rewind` semantics are not assumed. Keep durable state in the Markdown ledger before compacting.
+
+Persistent memory is off unless the tool inventory exposes an approved memory integration such as `recall`/`retain`. Always write `lessons.md` first. Never retain secrets, credentials, client data, personal data, or unvalidated hypotheses.
+
+## Commit and sharing
+
+- After D passes, offer a local repository-native commit only when the user requests it. Never push with that step.
+- `/share`, `pi share`, GitHub mutations, external Devin session creation, and other publication remain protected `post-web` actions.
+- Pi package extensions execute with local user permissions; the approval guard is not an OS sandbox.

package/skills/auto-mode-router/references/routing-matrix.md

@@ -0,0 +1,99 @@
+# Skill routing matrix
+
+Use one row after work type and skill mode are confirmed. Skill names are current preferred entry points; verify discovery before invoking them.
+
+Names such as `auto-reviewer` and `auto-security-reviewer` are packaged OMP agents. On Pi, treat them as role contracts and execute them sequentially unless a compatible subagent extension is detected.
+
+## A/B/C/D stage sequence
+
+Implementation routes insert a verification gate after B and before D. Type 5 and high-risk changes also insert a security gate before lessons. After the required review passes: lessons/memory → optional local commit → separately approved push/merge/publication.
+
+| Work type | Initial stages |
+|---|---|
+| 1 | A → C; add B → D only when implementation begins |
+| 2 | A → C → B → verification → D |
+| 3 | A → C → B → verification → D |
+| 4 | A → B → DAP/tests/UI verification → D; add C for a non-trivial plan |
+| 5 | A → C → security review; add B → verification → D → security verification for authorized fixes |
+| 6 | A → C |
+| 7 | A → C |
+
+Activate the saved stage model immediately before its stage. A and C must differ; B and D must differ.
+
+## 1 — New idea or development from scratch
+
+| Spine | Route |
+|---|---|
+| Compound Engineering | `ce-brainstorm`; then `ce-plan` only when the user moves from requirements to implementation |
+| Superpowers | `brainstorming`; then `writing-plans` after design approval |
+| GSD | `gsd-ideate` for exploration, `gsd-spike` for feasibility, or `gsd-project` for a new multi-phase project |
+
+Option 4 default: Compound Engineering for broad product framing; Superpowers for a focused design that will become code soon; GSD for a technical spike or a multi-milestone product.
+
+## 2 — New feature in an existing repository
+
+| Spine | Route |
+|---|---|
+| Compound Engineering | `ce-brainstorm` when requirements are unclear → `ce-plan` → `ce-work` → `ce-code-review` → `session-lessons`/`ce-compound` when warranted |
+| Superpowers | `brainstorming` → `using-git-worktrees` when isolation helps → `writing-plans` → `test-driven-development` → `subagent-driven-development` or `executing-plans` → `requesting-code-review` → `finishing-a-development-branch` |
+| GSD | `gsd-context`/onboard → `gsd-workflow` discuss → plan → execute → verify; `gsd-manage` ship only after approval |
+
+Option 4 default: Compound Engineering for one cohesive feature; Superpowers when strict TDD and task-by-task review are the dominant need; GSD for a large feature spanning phases or milestones.
+
+## 3 — Improve an existing feature
+
+| Spine | Route |
+|---|---|
+| Compound Engineering | `ce-optimize` for a measurable outcome, `ce-polish` for live UX refinement, or `ce-simplify-code` for settled code; finish with `ce-code-review` |
+| Superpowers | `brainstorming` for the desired behavior → `writing-plans` → `test-driven-development` → execution and review skills |
+| GSD | `gsd-context` → `gsd-workflow` for a scoped phase → `gsd-quality` verification/review |
+
+Option 4 default: Compound Engineering, because its polish, optimize, and simplify paths are specialized for improvement work.
+
+## 4 — Proactive bug discovery or bug fix
+
+| Spine | Route |
+|---|---|
+| Compound Engineering | `ce-dogfood` for browser-flow discovery, `ce-code-review` for code-level discovery, then `ce-debug` for root-cause repair and regression evidence |
+| Superpowers | `systematic-debugging` → `test-driven-development` for the regression barrier → `verification-before-completion` → `requesting-code-review` |
+| GSD | `gsd-quality` to route audit/debug/fix work, then `gsd-workflow` plan/execute/verify when the fix is non-trivial |
+
+Option 4 default: Compound Engineering for proactive discovery across user flows; Superpowers for a known reproducible defect; GSD for a bug program spanning several components. Do not let a discovery skill and a fix skill create separate competing plans.
+
+## 5 — Security review or fixes
+
+| Spine | Route |
+|---|---|
+| Compound Engineering | `ce-code-review` plus the read-only `auto-security-reviewer` and repository-native security tools; use `ce-debug` or `ce-work` only after findings are validated |
+| Superpowers | `systematic-debugging` and TDD can implement a validated fix, but Superpowers is not a complete security-audit framework; add `auto-security-reviewer` and scanners |
+| GSD | `gsd-quality` security/audit route → validate findings → plan fixes → execute → verify |
+
+Option 4 default: GSD when its security skills are available and compatible. Otherwise use the detected security reviewer plus repository-native scanners, with Compound Engineering owning the plan and fix. For high-risk auth, secrets, money, personal data, or public-contract changes, use an independent second model family for review.
+
+## 6 — Thoughts about an existing repository or feature
+
+| Spine | Route |
+|---|---|
+| Compound Engineering | `ce-pov` for a decisive assessment, `ce-explain` for teaching, or `ce-ideate` for grounded improvements |
+| Superpowers | `brainstorming` when the question should end in a proposed design; otherwise answer with read-only repository evidence |
+| GSD | `gsd-context` to map facts, then the appropriate read-only context or ideation route |
+
+Option 4 default: Compound Engineering for opinion or explanation; GSD for large-repository fact gathering.
+
+## 7 — Business, sales, or other non-technical analysis
+
+| Spine | Route |
+|---|---|
+| Compound Engineering | `ce-strategy`, `ce-pov`, or `ce-ideate`, depending on whether the output is a strategy, judgment, or option set |
+| Superpowers | No default business/sales spine. Use it only if a specifically relevant installed skill exists. |
+| GSD | No default business/sales spine. Do not force a software phase workflow onto non-technical analysis. |
+
+Option 4 default: Compound Engineering or a dedicated business/marketing/sales skill. Use web research when current market facts matter. Any publication, message, CRM write, social post, or external comment requires `post-web` approval.
+
+## Spine ownership rules
+
+- One family owns task state, plan, and execution checkpoints.
+- A supporting reviewer or scanner from outside the spine is allowed when it creates evidence rather than a second plan.
+- Do not run two brainstorming systems, two planning systems, or two shipping systems for the same task by default.
+- Switching spines is a recorded decision. Preserve the old artifacts, mark them superseded, and name the new authoritative plan.
+- `lfg`, GSD ship commands, and branch-finishing skills do not override approval rules. Push, PR creation/web posting, main push, and PR merge stop at their corresponding gate.

package/skills/auto-mode-router/references/session-ledger.md

@@ -0,0 +1,92 @@
+# Session ledger
+
+Every Auto Mode task keeps durable Markdown records.
+
+## Location
+
+Default:
+
+```text
+.agent-work/sessions/<YYYY-MM-DD>-<short-task-slug>/
+├── session.md
+├── plan.md
+├── decisions.md
+├── lessons.md       # created once at close
+└── evidence/        # only when the repo has no equivalent evidence location
+```
+
+Follow an existing repository convention when it provides an equivalent location. If the working directory is not writable, ask the user for an artifact directory rather than losing the ledger.
+
+## One source of planning truth
+
+The selected workflow family's native plan remains authoritative:
+
+- Compound Engineering: its generated brainstorm/plan document.
+- Superpowers: its generated design/implementation plan.
+- GSD: `.planning/` state and phase plans.
+- No technical spine: `plan.md` in the neutral session folder.
+
+The neutral `plan.md` is an index when a native plan exists. It records the goal, acceptance criteria, current phase, and a link/path to the authoritative plan; it does not duplicate the full plan.
+
+## `session.md`
+
+Record:
+
+```markdown
+# Auto Mode Session
+
+- Status: ready | active | blocked | completed | superseded
+- Work context: job-client | personal
+- Branding: client-project-only | existing-project-opt-in
+- Work type: 1..7 — <label>
+- Skill mode: 1..4
+- Primary spine: compound-engineering | superpowers | gsd | none
+- Current phase: intake | analysis | plan | build | verify | review | security | lessons | commit
+- Authoritative plan: <path or none>
+- Stage A model: <exact live selector>
+- Stage B model: <exact live selector or n/a>
+- Stage C model: <exact live selector>
+- Stage D model: <exact live selector or n/a>
+- Model separation: A != C; B != D
+- CodeGraph: n/a | pending | ready | blocked
+- Runtime: advisor=<off|available|on|unavailable>; orchestration=<serial|task|workflowz>; checkpoint=<off|available|used>
+- Add-ons: Ponytail=<setting>; memory=<off|local|hindsight-recall|hindsight-retain>; language skills=<names or none>; cost=<posture>
+- Verification: tests=<state>; DAP=<state>; UI=<browser|desktop|n/a and state>; security=<state>
+- Review verdict: pending | ship | block
+- Collaboration: off | view-approved | write-approved
+- Commit: not-ready | offered | created | skipped
+- Approval policy: ask
+- Lessons: pending | complete
+```
+
+Append a short evidence index as the work progresses, including unavailable or skipped verification gates and their consequence. Do not store secrets, credentials, private tokens, or unnecessary personal/client data.
+
+## `decisions.md`
+
+Use stable IDs:
+
+```markdown
+## D-001 — <decision>
+
+- Status: proposed | confirmed | superseded
+- Reason: <why>
+- Consequence: <what this changes>
+- Source: user | repository | evidence-backed recommendation
+```
+
+Record material product, architecture, security, scope, model, skill-spine, and approval decisions. Do not fill the file with routine implementation details already obvious from code.
+
+## `plan.md`
+
+At minimum record:
+
+- user-visible goal;
+- acceptance evidence;
+- highest-cost failure modes;
+- ordered phases or link to the authoritative native plan;
+- verification and review gates;
+- protected external actions still requiring approval.
+
+## Completion
+
+Only set `Status: completed` when acceptance evidence exists and `lessons.md` has `run_count: 1`. A clean Git tree alone is not completion evidence.

package/skills/codegraph-first/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: codegraph-first
+description: Establish CodeGraph as the architecture, dependency, flow, and impact authority for PiMarg work on an existing repository. Use for work types 2 through 6 before repository-wide claims; initialize and verify the graph, then combine it with any detected LSP/AST tools and precise reads.
+---
+
+# CodeGraph First
+
+Use CodeGraph as the source-navigation authority for an existing repository.
+
+## Bootstrap gate
+
+Before searching, reading, explaining, planning against, editing, or reviewing source code:
+
+1. Resolve and record the exact Git repository root. Do not guess a repository path.
+2. Check `command -v codegraph`.
+3. If the CLI is missing, pause source-code work and ask to install `@colbymchenry/codegraph`. Do not silently download or globally install it.
+4. If `<repo>/.codegraph/` is missing, run `codegraph init <repo>`. This is the required repo-local initialization for work types 2–6.
+5. Run `codegraph status <repo>` and require a usable index before continuing.
+
+On OMP, the package's `.mcp.json` can start `codegraph serve --mcp`; prefer `codegraph_explore`. On Pi, or when MCP is unavailable, use the verified CLI through `bash`. Invoke only subcommands shown by the installed version's help; CodeGraph versions may differ.
+
+## Source intelligence rule
+
+- Use CodeGraph for architecture, dependency relationships, call/data flows, candidate file discovery, and blast-radius analysis.
+- After CodeGraph establishes the relevant scope, use LSP when detected for exact definitions, references, types, diagnostics, code actions, and safe renames.
+- Use detected AST tooling for bounded structural queries and previewable rewrites when that is safer than text editing.
+- Treat source returned by CodeGraph as read. Do not re-run grep, ripgrep, glob, or a file-by-file crawl to verify it.
+- A direct file read is allowed only after CodeGraph identifies the precise file or symbol and an edit/hash-aware tool, compiler error, test failure, or exact-line verification needs the bytes.
+- Git status, Git diff, test output, build metadata, documentation, configuration, generated artifacts, and non-code text are not source discovery and may use their normal tools.
+- If CodeGraph does not support or cannot index the relevant source, stop structural discovery and report the exact limitation. LSP may still answer an exact symbol question when its language server is healthy; ask before falling back to grep/glob for source code.
+
+## Change loop
+
+Before an edit, use `impact` or the blast-radius result when shared behavior may change. After edits, honor the CodeGraph staleness/sync signal, then use `affected` to choose tests where relevant. Record the graph status and important paths in the Auto Mode evidence ledger.

package/skills/session-lessons/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: session-lessons
+description: Close an Auto Mode session by extracting verified, reusable lessons into Markdown exactly once. Use immediately before final completion or when `/auto-close` is invoked; do not use repeatedly during the same session.
+---
+
+# Session Lessons
+
+Find the active Auto Mode ledger. If `lessons.md` already contains `run_count: 1`, report that lessons are already complete and do not rewrite it.
+
+Otherwise:
+
+1. Read `session.md`, `plan.md`, `decisions.md`, the authoritative plan, and verification/review evidence.
+2. Separate observed evidence from guesses. Do not turn routine steps into durable lessons.
+3. Create `lessons.md` with YAML frontmatter:
+
+```yaml
+---
+run_count: 1
+session_status: completed
+---
+```
+
+4. Record only these useful sections:
+   - Outcome and evidence.
+   - What worked and should be repeated.
+   - What failed or surprised us.
+   - Reusable lesson or guardrail.
+   - Remaining unknowns or follow-up.
+5. Update `session.md` to `Lessons: complete`. Set the session status to `completed` only if the requested outcome is genuinely complete.
+6. When native `learn` or Hindsight `retain` is available and the recorded context policy permits it, save only the verified reusable guardrail and material decision summary. The Markdown lesson remains the durable session record even if memory retention fails.
+
+When Compound Engineering is the primary spine and the result contains a non-obvious repository learning, `ce-compound` may be used as the learning engine before writing this record. Do not invoke it for routine work just to satisfy ceremony. For every other case, this skill itself is the required once-per-session lesson step.
+
+Never include secrets or unnecessary employer/client information in the lessons file.