feat: add git-managed PAI context and session sync

agents/codemap.yml

@@ -0,0 +1,22 @@
+scope: module
+parent: ../codemap.yml
+sources_of_truth:
+  - path: product_manager.md
+    description: Bundled Product Manager Agent definition.
+  - path: workflow_runner.md
+    description: Bundled Workflow Runner Agent definition.
+  - path: business_analyst.md
+    description: Bundled Business Analyst Agent definition.
+  - path: technical_architect.md
+    description: Bundled Technical Architect Agent definition.
+  - path: tech_lead.md
+    description: Bundled Tech Lead Agent definition.
+  - path: developer.md
+    description: Bundled Developer Agent definition.
+  - path: qa_engineer.md
+    description: Bundled QA Engineer Agent definition.
+  - path: ui_ux_designer.md
+    description: Bundled UI/UX Designer Agent definition.
+commands:
+  - npm test
+  - npm run build

agents/product_manager.md

@@ -6,6 +6,11 @@ tools:
   nomadworks_validate: true
   nomadworks_start_discussion: true
   nomadworks_stop_discussion: true
+  nomadworks_session_export: true
+  nomadworks_session_import: true
+  nomadworks_sync_status: true
+  nomadworks_sync_pull: true
+  nomadworks_sync_push: true
   nomadflow_run_workflow: true
   nomadflow_prompt_workflow: true
 ---

agents/workflow_runner.md

@@ -3,6 +3,9 @@ description: Delegated workflow orchestrator for PMA-started complex task lifecy
 mode: subagent
 tools:
   nomadworks_validate: true
+  nomadworks_session_export: true
+  nomadworks_session_import: true
+  nomadworks_sync_status: true
 ---
 You are the NomadWorks Workflow Runner. You execute one PMA-started workflow lifecycle for one task file.
 

codemap.yml

@@ -0,0 +1,29 @@
+scope: repo
+modules:
+  - path: src
+    description: Plugin runtime source and validation logic.
+  - path: scripts
+    description: Build and release helper scripts.
+  - path: tests
+    description: Jest regression coverage.
+  - path: agents
+    description: Bundled NomadWorks agent prompt definitions.
+  - path: policies
+    description: Bundled shared policy documents.
+entrypoints:
+  - path: package.json
+    description: Package metadata, scripts, and published entrypoint declaration.
+sources_of_truth:
+  - path: package-lock.json
+    description: Locked npm dependency graph.
+  - path: README.md
+    description: Public package overview.
+  - path: Agents_Common.md
+    description: Shared prompt content included by bundled agents.
+invariants:
+  - Root CodeMap describes only immediate repository children; subdirectory internals belong to local codemap.yml files.
+  - Runtime state under hidden tool-owned directories is not indexed here.
+commands:
+  - npm test
+  - npm run build
+  - npm run release:check

docs/core/technical_guidelines.md

@@ -3,12 +3,12 @@
 This document defines the project's tech stack and architectural patterns.
 
 ## Tech Stack
-- **Language:** [To be defined]
-- **Runtime/Framework:** [To be defined]
-- **Frontend (if applicable):** [To be defined]
-- **State Management:** [To be defined]
-- **Testing Framework:** [To be defined]
-- **Database/Storage:** [To be defined]
+- **Language:** JavaScript ES modules, with TypeScript types available for Node compatibility checks.
+- **Runtime/Framework:** Node.js OpenCode plugin package using `@opencode-ai/plugin`.
+- **Frontend (if applicable):** Not applicable; NomadWorks is a CLI/plugin and documentation package.
+- **State Management:** File-backed repository configuration, workflow artifacts, and optional Git-managed PAI roots.
+- **Testing Framework:** Jest via `node --experimental-vm-modules`.
+- **Database/Storage:** Local filesystem plus Git repositories for durable project and PAI state.
 
 ## Architectural Patterns
 - **Feature-First:** Organize code into distinct features or modules.

docs/guides/TOOLS.md

@@ -82,6 +82,60 @@ This tool performs the full close flow synchronously:
 - archives the raw runtime transcript
 - returns the final closed result from the tool call itself
 
+## `nomadworks_session_export`
+
+Exports selected OpenCode sessions with the native sanitized `opencode export --sanitize <sessionID>` command into the workspace area of the Git-managed PAI root. If no `session_ids` are provided, it exports the current OpenCode session only when the runtime supplies a current session ID in tool context; otherwise it fails and asks for explicit session IDs.
+
+### Arguments
+
+- `session_ids`: optional OpenCode session IDs, separated by commas or whitespace. Uses the current session when empty.
+- `repo_path`: optional PAI root path. Uses `pai.root`, `sync.repo_path`, plugin `pai_root`, or plugin `sync_repo_path` when empty.
+- `opencode_command`: optional OpenCode executable path or command. Uses `pai.opencode_command` or `opencode` when empty.
+- `raw_export`: optional boolean. Defaults to `false`; set to `true` only to explicitly opt in to raw `opencode export <sessionID>` output.
+
+### Notes
+
+- Generated files live under `WORKSPACES/<repo-id>/SESSIONS/` inside the PAI repository. The `<repo-id>` is derived from the repository's stable Git identity, preferring the normalized remote URL/full name; `pai.workspace.id` can override it when necessary.
+- The configured PAI root must already be a Git repository with `.git` before export writes durable session state.
+- To export outside a live OpenCode session context, pass explicit `session_ids`.
+- Run `nomadworks_session_import` on another machine to import them with the native `opencode import <file>` command.
+
+## `nomadworks_session_import`
+
+Imports selected OpenCode sessions from native `opencode export` JSON files in the workspace area of the Git-managed PAI root.
+
+### Arguments
+
+- `session_ids`: optional session IDs to import. Imports all exported OpenCode sessions in the manifest when empty.
+- `repo_path`: optional PAI root path. Uses `pai.root`, `sync.repo_path`, plugin `pai_root`, or plugin `sync_repo_path` when empty.
+- `opencode_command`: optional OpenCode executable path or command. Uses `pai.opencode_command` or `opencode` when empty.
+
+### Notes
+
+- Uses the native `opencode import <file>` command in the current worktree.
+- The configured PAI root must already be a Git repository with `.git` before import reads durable session state.
+
+## `nomadworks_sync_status`
+
+Shows sync repository status for global PAI and the current workspace.
+
+### Arguments
+
+- `repo_path`: optional sync Git repository path. Uses `pai.root`, `sync.repo_path`, plugin `pai_root`, or plugin `sync_repo_path`.
+
+## `nomadworks_sync_pull`
+
+Runs `git pull --ff-only` in the configured sync repository. The configured PAI root must already be a Git repository with `.git`.
+
+## `nomadworks_sync_push`
+
+Runs `git add .`, `git commit`, and `git push` in the configured sync repository. The configured PAI root must already be a Git repository with `.git`. If there are no changes to commit, it returns status `no_changes` with `push: null` and does not run `git push`.
+
+### Arguments
+
+- `repo_path`: optional sync Git repository path.
+- `message`: optional commit message. Defaults to `sync nomadworks pai`.
+
 ## `nomadflow_run_workflow`
 
 Starts a `workflow_runner` session for a complex task.

docs/setup/CONFIGURATION.md

@@ -17,6 +17,7 @@ defaults:
 features:
   debug_dumps: true
   codemap_verification: true
+  # pai_context: false
 
 policies:
   extract_defaults: none
@@ -115,3 +116,55 @@ Create `.nomadworks/agents/<agent>.md` to:
 ## Feature flags
 
 - `features.keep_builtin_agents`: when `true`, NomadWorks will not disable agents that OpenCode already registered, including built-in agents such as `build`, `plan`, `general`, and `explore`. NomadWorks will still set `product_manager` as the default agent.
+- `features.pai_context`: when `true`, injects selected global and workspace PAI user files into configured agent prompts.
+
+## PAI plugin options
+
+NomadWorks can be configured globally in OpenCode with PAI root options:
+
+```json
+{
+  "plugin": [["@neuralnomads/nomadworks", {
+    "pai_root": "~/nomadworks-pai",
+    "sync_repo_path": "~/nomadworks-pai"
+  }]]
+}
+```
+
+- `pai_root`: Git-managed PAI root shared across repositories.
+- `sync_repo_path`: defaults Git operations to the same PAI root.
+
+These options may be supplied as tuple plugin options in OpenCode. Repository-local `pai.root` and `sync.repo_path` override global plugin defaults when present.
+
+## PAI context
+
+```yaml
+features:
+  pai_context: true
+
+pai:
+  root: ../nomadworks-pai
+  opencode_command: opencode
+  workspace:
+    enabled: true
+    # Optional stable override when the Git remote cannot identify this repo uniquely.
+    # id: neuralnomads-nomadworks
+    context_files:
+      - MEMORY/PROJECT.md
+      - MEMORY/DECISIONS.md
+      - MEMORY/NOTES.md
+  context_files:
+    - USER/ABOUTME.md
+    - USER/TELOS.md
+    - USER/AISTEERINGRULES.md
+  apply_to_agents:
+    - product_manager
+    - business_analyst
+    - tech_lead
+```
+
+When enabled, NomadWorks appends selected global PAI files first, then selected workspace PAI files. Both live in the Git-managed PAI root, outside the project repository. Global PAI uses `USER/`, `MEMORY/`, and `LEARNINGS/`; workspace PAI uses `WORKSPACES/<repo-id>/`. The workspace `<repo-id>` is derived from the repository's stable Git identity, preferring the normalized remote URL/full name rather than the local worktree folder name. Set `pai.workspace.id` only for edge cases where the Git identity is unavailable or must be overridden. Neither overrides repository truth, SCRs, task files, evidence, docs, or CodeMaps.
+
+Use `nomadworks_session_export` to export selected sessions using sanitized native `opencode export --sanitize <sessionID>` JSON by default. Raw exports require the explicit `raw_export: true` tool argument and should only be used when the caller accepts the sensitivity risk. When no `session_ids` are provided, export only works if the OpenCode runtime supplies the current session ID in the tool context; otherwise the tool returns a failure asking for explicit session IDs. Use `nomadworks_session_import` on another machine after `nomadworks_sync_pull` to import those files with native `opencode import <file>`.
+
+Use `nomadworks_sync_pull` and `nomadworks_sync_push` for Git. Git, not NomadWorks, handles text-file merges and conflicts in the PAI root. Mutating PAI/session tools fail fast unless the configured PAI root already contains `.git`. If there are no changes to commit, `nomadworks_sync_push` returns status `no_changes` and does not run `git push`. Global PAI lives under `USER/`, `MEMORY/`, and `LEARNINGS/`; repo-specific PAI lives under `WORKSPACES/<repo-id>/`.

policies/codemap.yml

@@ -0,0 +1,23 @@
+scope: module
+parent: ../codemap.yml
+sources_of_truth:
+  - path: README.md
+    description: Policy bundle overview.
+  - path: definition-of-ready.md
+    description: Definition of Ready policy.
+  - path: definition-of-done.md
+    description: Definition of Done policy.
+  - path: development-guidelines.md
+    description: Development policy.
+  - path: documentation-guidelines.md
+    description: Documentation policy.
+  - path: git-commit-messaging.md
+    description: Commit message policy.
+  - path: product-guidelines.md
+    description: Product guidance policy.
+  - path: testing-guidelines.md
+    description: Testing policy.
+  - path: ui-ux-guidelines.md
+    description: UI/UX policy.
+commands:
+  - npm test

scripts/codemap.yml

@@ -0,0 +1,11 @@
+scope: module
+parent: ../codemap.yml
+entrypoints:
+  - path: build.js
+    description: Builds the distributable plugin files into dist/.
+internals:
+  - path: resolve-release-version.js
+    description: Resolves release version metadata for packaging workflows.
+commands:
+  - npm run build
+  - npm run release:check

src/codemap.yml

@@ -0,0 +1,14 @@
+scope: module
+parent: ../codemap.yml
+entrypoints:
+  - path: index.js
+    description: NomadWorks OpenCode plugin entrypoint and tool wiring.
+internals:
+  - path: validate_logic.js
+    description: CodeMap and workflow artifact validation implementation.
+invariants:
+  - PAI durable sync state must stay outside the project worktree.
+  - Mutating PAI/session tools require a Git-backed PAI root.
+commands:
+  - npm test
+  - npm run build