singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
singularity-forge/docs/dev/agent-knowledge-index.md

223 lines
12 KiB
Markdown
Raw Permalink Normal View History

fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
# Agent Knowledge Index
Use this file as a machine-operational routing table for pi docs and research references.
Rules:
- Read only the specific files relevant to the current task.
- Prefer the primary bundle first.
- Read files in parallel when the task clearly maps to multiple known references.
- Use absolute paths directly with `read`.
- Follow conditional references only when the primary bundle does not answer the question.
## Pi architecture
Use when:
- understanding how pi works end to end
- tracing subsystem relationships
- understanding sessions, compaction, models, tools, or prompt flow
- deciding how to embed pi in a branded app, custom CLI, desktop app, or web product
Read first:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/what-is-pi/01-what-pi-is.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/04-the-architecture-how-everything-fits-together.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/05-the-agent-loop-how-pi-thinks.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
Read together when relevant:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/what-is-pi/06-tools-how-pi-acts-on-the-world.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/07-sessions-memory-that-branches.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/08-compaction-how-pi-manages-context-limits.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/09-the-customization-stack.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/10-providers-models-multi-model-by-default.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/13-context-files-project-instructions.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
Follow-up if needed:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/what-is-pi/03-the-four-modes-of-operation.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/11-the-interactive-tui.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/12-the-message-queue-talking-while-pi-thinks.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/14-the-sdk-rpc-embedding-pi.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/15-pi-packages-the-ecosystem.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/16-why-pi-matters-what-makes-it-different.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/17-file-reference-all-documentation.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/18-quick-reference-commands-shortcuts.md`
- `/Users/lexchristopherson/.sf/docs/what-is-pi/19-building-branded-apps-on-top-of-pi.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
## Context engineering, hooks, and context flow
Use when:
- understanding how user prompts flow through to the LLM
- working with before_agent_start, context, tool_call, tool_result, input hooks
- injecting, filtering, or transforming LLM context
- understanding message types and what the LLM actually sees
- coordinating multiple extensions
- building mode systems, presets, or context management extensions
- debugging why the LLM does or doesn't see certain information
Read first:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/01-the-context-pipeline.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/02-hook-reference.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
Read together when relevant:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/03-context-injection-patterns.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/04-message-types-and-llm-visibility.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/05-inter-extension-communication.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/06-advanced-patterns-from-source.md`
- `/Users/lexchristopherson/.sf/docs/context-and-hooks/07-the-system-prompt-anatomy.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
## Extension development
Use when:
- building or modifying extensions
- adding tools, commands, hooks, renderers, state, or packaging
Read first:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/extending-pi/01-what-are-extensions.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/02-architecture-mental-model.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/03-getting-started.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
Read together when relevant:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/extending-pi/06-the-extension-lifecycle.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/07-events-the-nervous-system.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/08-extensioncontext-what-you-can-access.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/09-extensionapi-what-you-can-do.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/10-custom-tools-giving-the-llm-new-abilities.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/11-custom-commands-user-facing-actions.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/14-custom-rendering-controlling-what-the-user-sees.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/25-slash-command-subcommand-patterns.md` # for subcommand-style slash command UX via getArgumentCompletions()
- `/Users/lexchristopherson/.sf/docs/extending-pi/15-system-prompt-modification.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/22-key-rules-gotchas.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
Follow-up if needed:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/extending-pi/04-extension-locations-discovery.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/05-extension-structure-styles.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/12-custom-ui-visual-components.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/13-state-management-persistence.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/16-compaction-session-control.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/17-model-provider-management.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/18-remote-execution-tool-overrides.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/19-packaging-distribution.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/20-mode-behavior.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/21-error-handling.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/23-file-reference-documentation.md`
- `/Users/lexchristopherson/.sf/docs/extending-pi/24-file-reference-example-extensions.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
## Pi UI and TUI
Use when:
- building dialogs, widgets, overlays, custom editors, or UI renderers
- working on TUI layout or display behavior
Read first:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/01-the-ui-architecture.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/03-entry-points-how-ui-gets-on-screen.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/22-quick-reference-all-ui-apis.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
Read together when relevant:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/04-built-in-dialog-methods.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/05-persistent-ui-elements.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/06-ctx-ui-custom-full-custom-components.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/07-built-in-components-the-building-blocks.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/12-overlays-floating-modals-and-panels.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/13-custom-editors-replacing-the-input.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/14-tool-rendering-custom-tool-display.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/15-message-rendering-custom-message-display.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/21-common-mistakes-and-how-to-avoid-them.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
Follow-up if needed:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/02-the-component-interface-foundation-of-everything.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/08-high-level-components-from-pi-coding-agent.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/09-keyboard-input-how-to-handle-keys.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/10-line-width-the-cardinal-rule.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/11-theming-colors-and-styles.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/16-performance-caching-and-invalidation.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/17-theme-changes-and-invalidation.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/18-ime-support-the-focusable-interface.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/19-building-a-complete-component-step-by-step.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/20-real-world-patterns-from-examples.md`
- `/Users/lexchristopherson/.sf/docs/pi-ui-tui/23-file-reference-example-extensions-with-ui.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
## Building coding agents
Use when:
- designing agent behavior
- improving autonomy, speed, context handling, or decomposition
- solving hard ambiguity, safety, or verification problems
Read first:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/01-work-decomposition.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/06-maximizing-agent-autonomy-superpowers.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/11-god-tier-context-engineering.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/12-handling-ambiguity-contradiction.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/26-cross-cutting-themes-where-all-4-models-converge.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
Read together when relevant:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/03-state-machine-context-management.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/04-optimal-storage-for-project-context.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/05-parallelization-strategy.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/07-system-prompt-llm-vs-deterministic-split.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/08-speed-optimization.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/10-top-10-pitfalls-to-avoid.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/17-irreversible-operations-safety-architecture.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/20-error-taxonomy-routing.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/24-security-trust-boundaries.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
Follow-up if needed:
refactor(native): rename gsd_parser.rs to forge_parser.rs Final rebrand: rename remaining Rust source file to complete the gsd → forge transition. All parser references already use forge_parser after earlier commits. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-15 14:58:21 +02:00
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/02-what-to-keep-discard-from-human-engineering.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/09-top-10-tips-for-a-world-class-agent.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/13-long-running-memory-fidelity.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/14-multi-agent-semantic-conflict-resolution.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/15-legacy-code-brownfield-onboarding.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/16-encoding-taste-aesthetics.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/18-the-handoff-problem-agent-human-maintainability.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/19-when-to-scrap-and-start-over.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/21-cost-quality-tradeoff-model-routing.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/22-cross-project-learning-reusable-intelligence.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/23-evolution-across-project-scale.md`
- `/Users/lexchristopherson/.sf/docs/building-coding-agents/25-designing-for-non-technical-users-vibe-coders.md`
fix: restore PR files lost during merge conflict resolution Files added by PR #2008 that were not in main were dropped during the merge. Restore all src/, docs/, and scripts/ files from the pre-merge PR head. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-25 22:38:55 -06:00
## Pi product docs
Use when:
- the user asks about pi itself, its SDK, extensions, themes, skills, packages, TUI, prompt templates, keybindings, or custom providers
Read first:
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/README.md`
Read together when relevant:
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/extensions.md`
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/themes.md`
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/skills.md`
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/prompt-templates.md`
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/tui.md`
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/keybindings.md`
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/sdk.md`
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/custom-provider.md`
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/models.md`
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/docs/packages.md`
Follow-up if needed:
- `/Users/lexchristopherson/.nvm/versions/node/v22.20.0/lib/node_modules/@mariozechner/pi-coding-agent/examples`
Reference in a new issue Copy permalink