Improve orchestration

.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Release npm package
+
+on:
+  push:
+    branches:
+      - dev
+      - main
+
+concurrency:
+  group: npm-release-${{ github.ref_name }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Verify package is releasable
+        run: npm run release:check
+
+      - name: Resolve publish version
+        id: resolve
+        run: node scripts/resolve-release-version.js "$GITHUB_REF_NAME" >> "$GITHUB_OUTPUT"
+
+      - name: Show resolved release plan
+        run: |
+          echo "branch=${GITHUB_REF_NAME}"
+          echo "package=${{ steps.resolve.outputs.package_name }}"
+          echo "channel=${{ steps.resolve.outputs.channel }}"
+          echo "version=${{ steps.resolve.outputs.version }}"
+          echo "publish_tag=${{ steps.resolve.outputs.publish_tag }}"
+          echo "should_publish=${{ steps.resolve.outputs.should_publish }}"
+          echo "reason=${{ steps.resolve.outputs.reason }}"
+
+      - name: Apply publish version
+        if: steps.resolve.outputs.should_publish == 'true'
+        run: npm version "${{ steps.resolve.outputs.version }}" --no-git-tag-version
+
+      - name: Publish package to npm
+        if: steps.resolve.outputs.should_publish == 'true'
+        run: npm publish --provenance --tag "${{ steps.resolve.outputs.publish_tag }}"
+
+      - name: Release summary
+        run: |
+          {
+            echo "## npm release"
+            echo ""
+            echo "- Branch: ${GITHUB_REF_NAME}"
+            echo "- Package: ${{ steps.resolve.outputs.package_name }}"
+            echo "- Channel: ${{ steps.resolve.outputs.channel }}"
+            echo "- Version: ${{ steps.resolve.outputs.version }}"
+            echo "- npm tag: ${{ steps.resolve.outputs.publish_tag }}"
+            echo "- Published: ${{ steps.resolve.outputs.should_publish }}"
+            echo "- Reason: ${{ steps.resolve.outputs.reason }}"
+          } >> "$GITHUB_STEP_SUMMARY"

Agents_Common.md

@@ -54,19 +54,20 @@ That document defines:
 ## 5. Operational Guidelines
 
 *   **Documentation Reading:** Whenever reading any file under `docs/` or `tasks/`, the file MUST be read fully to ensure complete understanding of the context and requirements. 
-*   **Role-Specific Guidelines:** Every agent is responsible for reading their specific guideline file from `docs/core/` at the start of their session (e.g., `developer_guidelines.md`, `qa_guidelines.md`).
+*   **Role-Specific Guidelines:** Every agent is responsible for reading the core guidance and any applicable repository policy includes that are part of their prompt.
+*   **Definition Of Ready / Done:** All execution should follow the repository's active Definition of Ready and Definition of Done policies.
 *   **Signed Agent Messages:** Agent-to-agent interactions must begin with a signed first message that clearly identifies the sending and receiving agents. Use this exact format on the first line: `[Agent Message] From: <agent_name> To: <agent_name>`. Example: `[Agent Message] From: product_manager To: tech_lead`. If a message does not begin with an agent signature, agents should assume they are speaking directly with the user.
 *   **Pre-task Clarification:** Before starting any task, thoroughly review requirements. If anything is missing, ambiguous, or insufficient, immediately stop and clearly state what is needed, requesting clarification from the manager agent. Do not proceed until all requirements are clear.
 *   **CodeMap-First Navigation:** Before broad repository search, agents should consult the most relevant `codemap.yml` chain for the area they are trying to understand. Use local, parent, root, or explicitly targeted module CodeMaps as the first navigation pass. If no suitable CodeMap exists or it is insufficient, agents may then expand into direct search and source inspection.
 *   **Sync-up Mode Evaluation:** When in Sync-up Mode, critically evaluate the provided task definition for completeness and clarity. Identify missing information and explain its cruciality.
 *   **Development Considerations:** Always keep in mind Security, Scalability, Maintainability, Error Handling, Performance, and Consistency.
 *   **Concise Communication:** Agent responses should be brief, direct, and non-repetitive. Do not restate the same point multiple times, and do not become overly verbose unless the user explicitly asks for more detail.
-*   **.gitignore Updates:** Whenever project setups are completed (e.g., adding new dependencies, features, or environments), ensure the `.gitignore` file is updated to exclude sensitive, temporary, or unnecessary files from version control.
+*   **.gitignore Updates:** Whenever repository changes introduce generated, temporary, or sensitive files, ensure ignore rules are updated appropriately.
 *   **Task Success Criteria:** No task is considered successful if there are failed tests, failed builds, or any other reason that prevents successful deployment. Any such issues must be fixed, even if the cause is not directly related to the current changes.
 *   **Acceptance Criteria Traceability:** Every task must define numbered acceptance criteria (`AC-1`, `AC-2`, ...) and the final evidence must trace verification back to those criteria.
 *   **Subagent Delegation:** No subagent simulation; we will be using actual subagents via the Task tool for every task delegation. When a task is assigned to a subagent, a task file MUST be provided, and the subagent MUST be instructed to read this file for detailed instructions. If a task is assigned without a task file, the subagent MUST strictly refuse to perform the task.
 *   **Economical Task Planning:** All agents should plan their tasks to be economical and smart to reduce requests usage. One such trick could be to use batched requests when appropriate.
-*   **External Dependency Management:** When setting up or integrating external dependencies, always use the latest stable version. If a dependency provides a utility or script for setup/initialization (e.g., `npm install`, `init` scripts), prefer using that utility to ensure correct configuration.
+*   **External Dependency Management:** Follow the repository's development policy when selecting, updating, or initializing external dependencies.
 *   **Post-Implementation Task Updates:** After completing their implementation step, each subagent MUST update the task file with a section titled `# Post Implementation Task Updates`, followed by a `## <Agent Name>: Post Implementation Expectations` heading. Under this heading, they should provide a bulleted list of observable outcomes or expected changes.
 *   **Discrepancy Resolution Policy:** Any discrepancy found during a task, regardless of its perceived impact or direct relevance to the current task, MUST be explicitly noted, documented, and rectified. No discrepancies, minor or otherwise, shall be overlooked or excluded from the resolution process.
 *   **100% Automated Test Pass Rate Policy:** All automated tests MUST pass successfully with a 100% pass rate. No 'expected skips' or failures are acceptable. Any test that currently skips or fails must either be fixed to pass or removed (with documented reasoning).
@@ -77,31 +78,25 @@ That document defines:
 *   **Task Lifecycle:** PMA reviews -> Updates task file -> Assigns next agent.
 *   **Discussion Tasks:** When a discussion between PMA, BA, and Tech Lead becomes workflow-relevant, it should be captured in a normal task file, assigned to the next responsible agent, and tracked under `Active Discussions` in `tasks/current.md` until it resolves into execution, SCR work, clarification, or closure.
 *   **Task Reopening:** If a task that was thought to be complete later needs unresolved discrepancies fixed or minor same-scope changes after implementation, reuse the same task file, move it back into `Active`, and record the reason in the task's `Reopen History` rather than creating a brand new task.
-*   **Resume Continuity:** When resuming a reopened task, keep the same task file ID. Reuse the same Task tool `task_id` for delegated task work when possible, and for workflow-runner execution reuse both the same Task tool `task_id` and the same Workflow Runner `session_id` when possible, so prior context remains available.
+*   **Resume Continuity:** When resuming a reopened task, keep the same task file ID. Reuse the same Task tool `task_id` for delegated task work when possible, and for Workflow Runner execution reuse both the same Task tool `task_id` and the same Workflow Runner `session_id` when possible, so prior context remains available.
 *   **Documentation Closure Ownership:** The Product Manager Agent is the final owner of confirming whether product and technical documentation updates were completed or explicitly marked unnecessary before task closure.
 *   **Git Strategy:** PMA remains the final workflow-closure authority. Tech Lead is the default commit authority for direct execution paths, and Workflow Runner may perform the delegated final commit only in explicit full-team complex workflows.
 *   **Authority Matrix:** Follow the canonical authority and output rules in `docs/core/role_contracts.md` for ownership, verification, commit authority, and closure decisions.
-*   **Commit Message Policy:** Every commit message must use a concise subject line in the format `<type>: <optional-task-id> <short summary>` and must include a brief body explaining exactly what the commit is for. If the commit is associated with a task, include the task ID in the subject.
-*   **Implementation Evidence Collection:** Every `implementation` task must produce an **Evidence Packet** in `evidences/[feature_task_name]/`. This MUST include:
-    *   `SUMMARY.md`: A brief explanation of what was tested and what the attached files prove.
-    *   `logs/`: Terminal output from verification commands.
-    *   `screenshots/`: Visual proof (mandatory for UI changes).
+*   **Commit Message Policy:** Every commit message must follow the repository's active commit messaging policy.
+*   **Implementation Evidence Collection:** Every `implementation` task must produce the verification artifacts required by the repository's testing and evidence policy.
 *   **Atomic Commitment:** A task is only complete when the code AND the "Truth" documentation (`docs/product/`, `docs/architecture/`, etc.) are updated in a single atomic commit. The SCR file is then marked as `Implemented`.
 *   **Batch Integrity:** In delegated workflow mode, the PMA should aim to complete the entire assigned batch. If a single task is blocked, it is isolated in `tasks/blocked/`, and the PMA continues with the rest of the batch if possible.
 
-## 7. Mandatory Documentation Update Matrix
+## 7. Repository Documentation Policy
 
-Every task MUST ensure the following files are updated if relevant:
+All documentation updates must follow the repository's documentation policy for:
 
-| Document Level | File Path | Responsible Agent |
-| :--- | :--- | :--- |
-| **Product Overview** | `docs/product/PRODUCT_OVERVIEW.md` | Business Analyst |
-| **Features List** | `docs/product/FEATURES_LIST.md` | Business Analyst |
-| **Architecture** | `docs/architecture/TECHNICAL_ARCHITECTURE.md` | Technical Architect |
-| **Feature Spec** | `docs/features/[feature]/SPECIFICATION.md` | BA & Architect |
-| **Tech Guidelines** | `docs/core/technical_guidelines.md` | Tech Lead / Architect |
-| **CodeMap** | `codemap.yml` | Developer / Architect |
+- where steady-state product and technical truth belongs
+- which documents must be updated for a given change
+- documentation ownership, naming, and layout conventions
 
-<include:docs/core/documentation_structure.md>
-<include:docs/core/role_contracts.md>
-<include:docs/core/task_model.md>
+<include:plugin:docs/core/role_contracts.md>
+<include:policy:definition-of-ready.md>
+<include:policy:definition-of-done.md>
+<include:policy:documentation-guidelines.md>
+<include:plugin:docs/core/task_model.md>

README.md

@@ -23,7 +23,27 @@ PMA will guide the repository setup flow and, when needed, initialize NomadWorks
 
 ## Configure
 
-During setup, PMA can initialize the repository and create `.codenomad/nomadworks.yaml`. NomadWorks reads this file for repository-local defaults, feature flags, and per-agent overrides.
+During setup, PMA can initialize the repository and create `.nomadworks/nomadworks.yaml`. NomadWorks reads this file for repository-local defaults, feature flags, policy extraction settings, and per-agent config overrides.
+
+Repository-local policy overrides live in `.nomadworks/policies/`. If a policy file is not present there, NomadWorks falls back to the bundled plugin default automatically.
+
+Repository-local full agent definitions can live in `.nomadworks/agents/`. Use this folder to override a bundled agent's base prompt or define a brand new custom repository agent.
+
+Repository-specific additive agent instructions can live in `.nomadworks/agent-additions/`.
+
+## Repository Customization
+
+- `.nomadworks/policies/*.md`: shared repository policy overrides used by multiple agents
+- `.nomadworks/agents/<agent>.md`: full repository-local agent definition that overrides a bundled agent or defines a new custom agent
+- `.nomadworks/agent-additions/<agent>.md`: additive repository-specific instructions appended to a bundled or custom agent prompt
+- `.nomadworks/generated/agents/`: generated final prompt dumps for inspection when `features.debug_dumps` is enabled
+- `.nomadworks/generated/policies/`: generated reference copies of bundled default policies when `policies.extract_defaults` is set to `all`
+
+`nomadworks_init` also creates README placeholders in these folders so repositories can discover what each folder is for without those README files being treated as agents.
+
+The scaffolded README files in `.nomadworks/agents/` and `.nomadworks/agent-additions/` also list the common available `plugin:` and `policy:` includes that custom agents can reuse.
+
+Runtime prompt resolution prefers repository-local policies, agent definitions, and agent additions when present, while keeping the plugin-owned workflow and role model intact by default.
 
 NomadWorks supports two team presets:
 
@@ -36,13 +56,24 @@ Quick links:
 
 - [Installation](docs/setup/INSTALLATION.md)
 - [Configuration](docs/setup/CONFIGURATION.md)
+- [Releasing](docs/setup/RELEASING.md)
 - [Workflow Agents](docs/guides/AGENTS.md)
 - [Workflow Model](docs/guides/WORKFLOW.md)
 - [Plugin Tools](docs/guides/TOOLS.md)
 - [Mini Team Mode](docs/guides/TEAM_MODE_MINI.md)
 - [Full Team Mode](docs/guides/TEAM_MODE_FULL.md)
 - [Documentation Structure](docs/core/documentation_structure.md)
 
+## Release
+
+NomadWorks ships as the npm package `@neuralnomads/nomadworks`.
+
+- Local verification: `npm run release:check`
+- Push to `dev`: auto-publish prerelease (`rc`)
+- Push to `main`: auto-publish stable release
+
+For the full release setup, required secrets, and branch-based versioning behavior, see [Releasing](docs/setup/RELEASING.md).
+
 ## Team Modes
 
 | Team Mode | Available Agents | Supported Task Complexity | Flow Guide |
@@ -55,7 +86,7 @@ Quick links:
 The NomadWorks Collective operates like a role-based software development team:
 
 - `product_manager` (Product Manager Agent, PMA): Default orchestrator and routing agent.
-- `workflow_runner` (Workflow Runner): Delegated executor for complex implementation tasks.
+- `workflow_runner` (Workflow Runner): Delegated orchestrator for complex implementation tasks.
 - `business_analyst` (Business Analyst, BA): Requirements and product-truth steward.
 - `technical_architect` (Technical Architect): Architecture, interfaces, and impact mapping.
 - `tech_lead` (Tech Lead): Behavioral verification and technical sign-off.

agents/business_analyst.md

@@ -31,6 +31,6 @@ Critically evaluate the provided task definition. Ensure it contains all necessa
 *   **Logical:** Constructs unambiguous user stories and acceptance criteria.
 *   **Inquisitive:** Proactively identifies gaps and hidden assumptions in task definitions.
 
-<include:Agents_Common.md>
-<include:docs/core/discussion_agent_guidelines.md>
-<include:docs/core/business_analyst_guidelines.md>
+<include:plugin:Agents_Common.md>
+<include:plugin:docs/core/discussion_agent_guidelines.md>
+<include:policy:product-guidelines.md>

agents/developer.md

@@ -30,6 +30,7 @@ Critically evaluate the task definition. Ensure it has sufficient detail for you
 *   **Consistent:** Adheres strictly to established project patterns and standards.
 *   **Collaborative:** Communicates clearly and works effectively within the orchestrated workflow.
 
-<include:Agents_Common.md>
-<include:docs/core/testing_strategy.md>
-<include:docs/core/codemap_conventions.md>
+<include:plugin:Agents_Common.md>
+<include:policy:development-guidelines.md>
+<include:policy:testing-guidelines.md>
+<include:plugin:docs/core/codemap_conventions.md>

agents/product_manager.md

@@ -40,7 +40,7 @@ You are the Product Manager Agent (PMA). You are the central orchestrator for al
         - Orchestrate the Post-Task Sync yourself when you retain control of the task lifecycle.
         - Ensure evidence, documentation closure, finalization updates, final commit, and archiving are completed before closure.
 *   **Delegated Batch Execution:** When the PO triggers a batch of implementation SCRs, execute them sequentially within the shared worktree. Investigation and spec tasks may still run in parallel when they are isolated from the active implementation task.
-*   **Post-Task Sync & Evidence:** You are the gatekeeper of the **Evidence Packet**. Ensure the Developer/QA has provided a `SUMMARY.md`, logs, and screenshots before calling the specialists for the Post-Task Sync. Instruct each specialist to **introduce themselves and their role** when providing verification feedback.
+*   **Post-Task Sync & Evidence:** You are the gatekeeper of implementation evidence. Ensure the Developer/QA has provided the verification artifacts required by the repository testing/evidence policy before calling the specialists for the Post-Task Sync. Instruct each specialist to **introduce themselves and their role** when providing verification feedback.
 *   **Bounce Back Protocol:** If an implementation is rejected during the Post-Task Sync, reuse the original Task tool `task_id` when sending it back to the agent. This ensures they have the full execution history of the rejection.
 *   **Formal Reopen Protocol:** If a task was marked done but later needs discrepancies fixed or minor same-scope changes after implementation, move that same task back into `Active`, append a `Reopen History` entry, and continue using the same task file ID. Reuse the same Task tool `task_id` when resuming delegated task work, and when resuming Workflow Runner execution, reuse both the same Task tool `task_id` and the same Workflow Runner `session_id` when possible.
 *   **Commit Authority:** You own final closure in all modes. Tech Lead is the default commit authority for direct execution paths, while Workflow Runner may perform the final commit only when you explicitly delegated a full-team complex workflow to it.
@@ -52,7 +52,8 @@ You are the Product Manager Agent (PMA). You are the central orchestrator for al
 *   **Strategic:** Focused on long-term goals and how current decisions contribute to them.
 *   **Decisive:** Able to make clear decisions and drive the product forward.
 
-<include:Agents_Common.md>
-<include:docs/core/discussion_agent_guidelines.md>
-<include:docs/core/agent_orchestration.md>
-<include:docs/core/communication_guidelines.md>
+<include:plugin:Agents_Common.md>
+<include:policy:product-guidelines.md>
+<include:plugin:docs/core/discussion_agent_guidelines.md>
+<include:plugin:docs/core/agent_orchestration.md>
+<include:plugin:docs/core/communication_guidelines.md>