feat(container): dynamic system prompts and agent cleanup

CLAUDE.md

@@ -2,6 +2,8 @@
 
 This repository contains three packages. Each package manages its own dependencies independently.
 
+For codebase navigation, see [TOUR.md](TOUR.md).
+
 ## Packages
 
 | Package | Runtime | Package Manager |

TOUR.md

@@ -0,0 +1,51 @@
+# Codebase Tour
+
+## Quick Reference
+
+- **Repo shape:** Monorepo with 3 independent packages — `container/`, `cli/`, `docs/`
+- **Languages/Runtimes:** Node.js (container, docs), TypeScript on Bun (cli), Python via pytest (container plugin tests)
+- **Package Managers:** npm (`container/`, `docs/`), bun (`cli/`)
+- **Test Frameworks:** pytest + `test.js` (container), `bun test` (cli), `astro build` with `starlight-links-validator` (docs)
+- **Entry Points:** `container/setup.js`, `cli/src/index.ts`, `docs/astro.config.mjs`
+- **Build commands:** `cd container && npm test` · `cd cli && bun test` · `cd docs && npm run build`
+
+## If you need to find...
+
+**Devcontainer install/setup logic**: Start at `container/setup.js` (the `@coredirective/cf-container` npm entry — copies `.devcontainer/` into target projects with checksum/update/preserve semantics). Runtime container declaration is `container/.devcontainer/devcontainer.json` (features, settings, port mappings). The `postStartCommand` orchestrator is `container/.devcontainer/scripts/setup.sh`, which dispatches gated `setup-*.sh` subscripts based on `container/.codeforge/container.json` flags.
+
+**Plugin system**: Plugins live at `container/.devcontainer/plugins/devs-marketplace/plugins/`. There are 13 plugins: `agent-system`, `auto-code-quality`, `codeforge-lsp`, `dangerous-command-blocker`, `git-workflow`, `notify-hook`, `prompt-snippets`, `protected-files-guard`, `session-context`, `skill-engine`, `spec-workflow`, `ticket-workflow`, `workspace-scope-guard`. Plugin hook scripts are Python; unit tests are in `container/tests/plugins/` (loaded via `importlib` for isolation).
+
+**Claude Code config defaults and deploy manifest**: Packaged defaults are in `container/.devcontainer/defaults/codeforge/`. Deploy logic is driven by `container/.devcontainer/defaults/codeforge/file-manifest.json` (id/src/dest/overwrite per file). Project-only overrides and state live in `container/.codeforge/` — never put defaults there.
+
+**System prompts and Claude profiles**: Master template at `container/.devcontainer/defaults/codeforge/claude/system-prompts/template.md` (Jinja2; composes 14 component partials in `components/`, renders to `main.md`/`orchestrator.md`/`writing.md`). Claude Code settings base + model/context profile overlays: `container/.devcontainer/defaults/codeforge/claude/settings/base.json` and `claude/settings/profiles/*.json`; rendered via `generate-settings-profiles.js`.
+
+**CLI commands and command registry**: Entry point `cli/src/index.ts` wires all `registerXxxCommand(parent)` modules. Commands live in `cli/src/commands/<domain>/`. Data access is centralized in `cli/src/loaders/` (reads `~/.claude/` files); output rendering in `cli/src/output/` (text/json/stats per domain).
+
+**`codeforge session search`**: Command module `cli/src/commands/session/search.ts`. Streaming JSONL engine `cli/src/search/engine.ts`; boolean AND/OR/NOT parser `cli/src/search/query-parser.ts`; wire types `cli/src/schemas/session-message.ts`.
+
+**`codeforge doctor` (environment diagnostics)**: `cli/src/commands/doctor/index.ts` — parallel health checks with `--fix` interactive mode.
+
+**Container-proxy detection**: `cli/src/utils/context.ts` — `isInsideContainer()` and the auto-proxy that re-runs the CLI inside the container via `docker exec` when invoked from the host.
+
+**Codebase indexer**: `cli/src/indexer/` — SQLite-backed symbol index (extractor, scanner, folder rules).
+
+**Plugin management commands**: `cli/src/commands/plugin/` (`list`, `show`, `enable`, `disable`, `hooks`, `agents`, `skills`).
+
+**Documentation pages**: Content in `docs/src/content/docs/`, organized by Starlight topic (`start-here/`, `use/`, `customize/`, `extend/`, `reference/`). One MDX per CodeForge plugin under `extend/plugins/`. Sidebar/topic structure is defined entirely in `docs/astro.config.mjs` — content file + sidebar entry must stay in sync. Content collections registered in `docs/src/content.config.ts`. Custom slot overrides: `docs/src/components/Hero.astro`, `docs/src/components/Header.astro`.
+
+**Changelog (single source of truth)**: `container/.devcontainer/CHANGELOG.md`. The docs site mirrors it via `docs/scripts/sync-changelog.mjs` (auto-runs before `dev` and `build`) — never edit `docs/src/content/docs/reference/changelog.md` directly; it's generated.
+
+**AI assistant reference for the devcontainer**: `container/.devcontainer/AGENTS.md` is the authoritative reference (commands, config, plugins, auth, modification procedures). `container/.devcontainer/AI-CONTEXT.md` is the machine-readable summary with a hard ~700-token ceiling.
+
+**Per-project overrides and state**: `container/.codeforge/container.json` — setup flags, identity, timezone, versionLock, plugin blacklist. Any new override file needs a manifest entry.
+
+**Compose-secret generation**: `container/.devcontainer/scripts/generate-compose.mjs` — `initializeCommand`; discovers `container/.codeforge/secrets/` files and emits Docker Compose secret mounts.
+
+## Conventions
+
+- **Changelog discipline**: Every change requires an entry in `container/.devcontainer/CHANGELOG.md`, grouped under `###` domain headings (e.g. `### Security`, `### Agent System`). Cross-package changes belong in a single PR, grouped by package in the commit message.
+- **Branching**: feature/fix branches → `staging` (integration) → `main` (release). PRs from `staging` to `main` are used for releases. Never commit directly to `main`.
+- **Per-package dependencies**: Each package manages its own dependencies — no root lockfile. Run tests in the affected package(s) before committing.
+- **Defaults vs. overrides**: Packaged defaults live in `container/.devcontainer/defaults/codeforge/`; `container/.codeforge/` is project-override and state only.
+- **Disabling a devcontainer feature**: Set `"version": "none"` in its block in `devcontainer.json` — do not remove the entry (preserves install order).
+- **`workspace-scope-guard` is load-bearing**: Do not disable it without explicit user instruction — it enforces file-operation scoping across all agents.

cli/CLAUDE.md

@@ -0,0 +1,53 @@
+# cli
+
+TypeScript/Bun CLI (`codeforge`) for CodeForge development workflows — session search, plugin management, devcontainer control, and environment diagnostics.
+
+Entry: `src/index.ts` — commander root; registers all subcommands and the container-proxy `preAction` hook.
+
+## Key Files
+
+- `src/index.ts` — program root; proxy middleware (auto-forwards to container when outside one)
+- `src/commands/session/search.ts` — `codeforge session search`; boolean query, role/project/time filters
+- `src/search/engine.ts` — JSONL streaming search engine; `SearchOptions`, `SearchResult`, `readLines`
+- `src/search/query-parser.ts` — AND/OR/NOT AST query parser used by the engine
+- `src/search/filter.ts` — `createFilter(FilterOptions)` predicate factory
+- `src/schemas/session-message.ts` — JSONL message types (`SessionMessage`, `SearchableMessage`, extractors)
+- `src/loaders/` — file-system loaders: `history-loader`, `session-meta`, `plan-loader`, `task-loader`, `plugin-loader`, `hooks-loader`, `settings-writer`
+- `src/output/` — formatters keyed by domain: `text.ts`, `json.ts`, `stats.ts`, `session-list.ts`, `session-show.ts`, `plugin-*.ts`, etc.
+- `src/utils/context.ts` — `isInsideContainer()`, `proxyCommand()` (docker exec)
+- `src/utils/time.ts` — `parseRelativeTime()`, `parseTime()` used by all date-filtered commands
+- `src/commands/doctor/index.ts` — `codeforge doctor`; parallel health checks, `--fix` mode
+
+## Subdirectories
+
+- `src/commands/` — one subdirectory per command group: `session/`, `task/`, `plan/`, `plugin/`, `hooks/`, `config/`, `index/`, `container/`, `mount/`, `doctor/`
+- `src/search/` — query parsing, filtering, and JSONL stream engine
+- `src/loaders/` — data access layer (reads Claude Code files from `~/.claude/`)
+- `src/schemas/` — TypeScript interfaces for JSONL wire formats
+- `src/output/` — rendering layer; formatters per domain and format (text/json/stats)
+- `src/utils/` — shared utilities: context, docker, glob, time, platform, mitmproxy
+- `src/indexer/` — codebase symbol index: `db.ts`, `extractor.ts`, `scanner.ts`, `folders.ts`
+- `tests/` — bun test suites, one file per module area
+
+## Dependencies
+
+Imports from: `commander`, `@clack/prompts`, `chalk`, `@devcontainers/cli`
+Used by: container package (ships the compiled binary); `codeforge` binary on PATH inside devcontainer
+
+## Conventions
+
+- Every command module exports a single `registerXxxCommand(parent: Command): void` function; registered in `src/index.ts`.
+- Command actions wrap their body in `try/catch`; errors print `Error: <message>` to stderr and call `process.exit(1)`.
+- Output format controlled by `--format text|json` option; color disabled via `chalk.level = 0` when `--no-color` is passed.
+- Loaders live in `src/loaders/`; formatters live in `src/output/`; commands are thin orchestrators that call both.
+- Use `Bun.file().stream()` (not `fs.readFile`) for JSONL streaming; see `readLines` in `engine.ts`.
+
+## Build & Test
+
+```
+bun run build               # bundle to dist/codeforge.js (bun target)
+bun run dev                 # run src/index.ts directly
+bun test                    # run all tests
+bun run build:binary        # compile self-contained binary
+bun run build:binary:linux  # cross-compile for linux-x64
+```

container/.devcontainer/CLAUDE.md

@@ -1 +1,55 @@
-@AGENTS.md
+# .devcontainer
+
+The CodeForge devcontainer definition — features, plugins, scripts, config defaults, and AI documentation.
+
+Entry: `AGENTS.md` — authoritative reference for all AI assistants; covers config keys, commands, plugins, auth, and modification procedures.
+
+## Key Files
+
+- `devcontainer.json` — container definition: 34+ features, VSCode settings/extensions, port mappings, postStartCommand
+- `docker-compose.yml` — base Compose file: image, named volumes, resource limits
+- `scripts/setup.sh` — postStartCommand orchestrator; runs all setup-*.sh subscripts, reads flags from `.codeforge/container.json`
+- `scripts/generate-compose.mjs` — initializeCommand; discovers `.codeforge/secrets/` and generates `docker-compose.codeforge.yml`
+- `scripts/generate-settings-profiles.js` — generates `.generated/codeforge/claude/settings/settings*.json` from base.json + profiles
+- `defaults/codeforge/file-manifest.json` — controls which config files deploy to `~/.claude/` on container start; each entry has `id`, `src`, `dest`, `overwrite` (`if-changed`|`always`|`never`)
+- `CHANGELOG.md` — user-facing change history (required entry for every PR)
+- `AI-CONTEXT.md` — machine-readable environment facts for AI assistants (~700 token target)
+
+## Subdirectories
+
+- `features/` — 34 custom devcontainer features (see list below)
+- `plugins/devs-marketplace/` — single marketplace plugin bundle; contains 12 Claude Code plugins under `plugins/`
+- `scripts/` — setup-*.sh subscripts + generate-compose.mjs + generate-settings-profiles.js
+- `defaults/codeforge/` — packaged config defaults deployed on every container start
+  - `claude/settings/` — `base.json` (shared settings) + `profiles/*.json` (model overlays)
+  - `claude/system-prompts/` — `template.md` (Jinja2), `main.md`, `orchestrator.md`, `writing.md`, `claude-default.md`, `components/` (14 partials)
+  - `claude/rules/` — behavioral rules deployed to `~/.claude/rules/` every start
+  - `claude/router/` — LLM provider routing config
+  - `claude/statusline/` — ccstatusline widget layout
+  - `rtk/`, `codex/` — tool-specific configs
+
+## Features (custom, under features/)
+
+agent-browser, ast-grep, biome, ccburn, ccdiag, ccms, ccstatusline, ccusage, chromaterm, claude-code-karma, claude-code-native, claude-code-router, claude-mem, claude-monitor, claude-session-analyzer, codeforge-cli, codex-cli, dprint, hadolint, hermes-agent, kitty-terminfo, lamarck, lsp-servers, mcp-qdrant, notify-hook, oh-my-claude, rtk, ruff, sandcastle, shellcheck, shfmt, tmux, tree-sitter, zsh-completions
+
+## Plugins (under plugins/devs-marketplace/plugins/)
+
+Active: agent-system, auto-code-quality, dangerous-command-blocker, protected-files-guard, session-context, skill-engine, workspace-scope-guard, codeforge-lsp
+Archived/disabled: git-workflow, notify-hook, prompt-snippets, spec-workflow, ticket-workflow
+
+## System Prompt Architecture
+
+`defaults/codeforge/claude/system-prompts/` uses a Jinja2 template system:
+- `template.md` — master template with named blocks (`{% block identity %}`, etc.) and `{% include "components/…" %}` directives
+- `components/` — 14 partial files (identity, guardrails, task-approach, decision-authority, task-intake, code-quality, communication, platform, context-management, tools, subagent-routing, error-recovery, self-review, memory)
+- `main.md`, `orchestrator.md`, `writing.md` — rendered variants (deployed via file-manifest)
+- `claude-default.md` — fallback prompt for unmodified deployments
+
+## Conventions
+
+- Feature install order is explicit in `devcontainer.json` `overrideFeatureInstallOrder` — runtimes first, then Claude Code, then npm/uv-dependent tools
+- Disable a feature without removing it: set `"version": "none"` in its config block
+- `overwrite: "never"` entries in file-manifest are one-time seeds (user owns them after first deploy)
+- Plugin hook scripts are Python; tested directly via importlib in `container/tests/plugins/`
+- AGENTS.md is the source of truth for AI assistants; AI-CONTEXT.md is the machine-readable summary (~700 token hard ceiling)
+- `workspace-scope-guard` MUST NOT be disabled without explicit user instruction