fix: use build venv in Gitea publish workflow (PEP 668)

Haskelseed runner blocks system-wide pip installs. Create an isolated .build-venv for build/twine and document workflow_dispatch API path.
docs: mark Helix reciprocal link verified (WP-0005 T16)
2026-06-16 07:15:57 +02:00 · 2026-06-16 07:13:13 +02:00 · 2026-06-16 03:27:41 +02:00 · 2026-06-16 03:25:41 +02:00 · 2026-06-16 03:13:01 +02:00 · 2026-06-16 02:26:13 +02:00
49 changed files with 760 additions and 194 deletions
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -8,24 +8,31 @@ on:

 jobs:
  test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.10", "3.12"]
+    runs-on: haskelseed
    steps:
      - name: Check out source
-        uses: actions/checkout@v4
-
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
+        env:
+          PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
+        run: |
+          git clone --depth 1 \
+            "https://tegwick:${PACKAGE_TOKEN}@gitea.coulomb.social/coulomb/kaizen-agentic.git" \
+            repo
+          cd repo
+          git checkout "${{ gitea.sha }}"

      - name: Install package and dev tools
-        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+        run: |
+          cd repo
+          python3 -m ensurepip --upgrade 2>/dev/null || \
+            curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py && python3 /tmp/get-pip.py
+          python3 -m pip install --upgrade pip
+          python3 -m pip install -e ".[dev]"

      - name: Format check (black)
-        run: black --check src tests
+        run: cd repo && black --check src tests
+
+      - name: Lint (flake8)
+        run: cd repo && flake8 src/ --max-line-length=100

      - name: Run tests
-        run: pytest tests/ -q --ignore=tests/test_cli_error_handling.py
+        run: cd repo && pytest tests/ -q --ignore=tests/test_cli_error_handling.py
--- a/.gitea/workflows/publish-python-package.yml
+++ b/.gitea/workflows/publish-python-package.yml
@@ -0,0 +1,36 @@
+name: Publish Python package
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: haskelseed
+    steps:
+      - name: Check out source
+        env:
+          PACKAGE_TOKEN: ${{ secrets.PACKAGE_TOKEN }}
+        run: |
+          git clone --depth 1 \
+            "https://tegwick:${PACKAGE_TOKEN}@gitea.coulomb.social/coulomb/kaizen-agentic.git" \
+            repo
+          cd repo
+          git checkout "${{ gitea.sha }}"
+
+      - name: Build and publish
+        env:
+          TWINE_USERNAME: ${{ secrets.PACKAGE_USER }}
+          TWINE_PASSWORD: ${{ secrets.PACKAGE_TOKEN }}
+        run: |
+          cd repo
+          python3 -m venv .build-venv
+          . .build-venv/bin/activate
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+          python -m twine upload \
+            --repository-url https://gitea.coulomb.social/api/packages/coulomb/pypi \
+            dist/*
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+### Added
+- **`make agents-sync-package`** — sync `agents/` into packaged `data/agents/`
+- **Packaged agent parity test** — `release-check` fails when wheel data drifts from source
+- **Gitea CI flake8** — lint gate on `src/` in `.gitea/workflows/ci.yml`
+
+### Changed
+- **Install documentation** — HELLO_WORLD, CLI_CHEAT_SHEET, AGENT_DISTRIBUTION use Gitea PyPI extra index
+- **`docs/PACKAGE_RELEASE.md`** — secrets setup and pre-tag release checklist
+
 ## [1.1.0] - 2026-06-18

 ### Added
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -32,6 +32,12 @@ pip install -e .              # project venv
 pipx install -e . --force     # global pipx install
 ```

+**Consumers (pip install from registry):** see [docs/PACKAGE_RELEASE.md](docs/PACKAGE_RELEASE.md)
+for Gitea PyPI credentials and `--extra-index-url` install paths.
+
+**Maintainers (release):** `make agents-sync-package` before tagging when `agents/` changes;
+`make package-check` and the pre-tag checklist in `docs/PACKAGE_RELEASE.md`.
+
 ## Development Workflow

 ### Project Structure
--- a/90
+++ b/90
@@ -1,11 +1,14 @@
 # Makefile for Kaizen Agentic development tasks

-.PHONY: help setup-complete setup-structure setup-python setup-tools setup-docs setup-tests setup-verify ensure-project-structure install-dev install-local install-global standards-check standards-fix standards-test test test-all build clean lint format venv-status agents-list agents-update agents-validate agents-status agents-install-cli release-check release-prepare release-test release-publish release-finalize release-rollback
+.PHONY: help setup-complete setup-structure setup-python setup-tools setup-docs setup-tests setup-verify ensure-project-structure install-dev install-local install-global standards-check standards-fix standards-test test test-all build clean lint format venv-status agents-list agents-update agents-validate agents-status agents-sync-package agents-install-cli release-check release-prepare release-test release-publish publish-gitea package-check release-finalize release-rollback

 # Variables
 VENV = .venv
 VENV_PYTHON = $(VENV)/bin/python
 VENV_PIP = $(VENV)/bin/pip
+GITEA_PACKAGE_OWNER ?= coulomb
+GITEA_PYPI_REPOSITORY_URL ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi
+GITEA_PYPI_SIMPLE_URL ?= https://gitea.coulomb.social/api/packages/$(GITEA_PACKAGE_OWNER)/pypi/simple/

 # Default target
 help:
@@ -38,13 +41,16 @@ help:
 	@echo "  agents-update   - Update agents to latest versions"
 	@echo "  agents-validate - Validate agent definitions"
 	@echo "  agents-status   - Show agent status and project info"
+	@echo "  agents-sync-package - Sync agents/ into packaged data/agents/ (DRY_RUN=1 to preview)"
 	@echo "  agents-install-cli - Install kaizen-agentic CLI tool"
 	@echo ""
 	@echo "Release Management:"
 	@echo "  release-check   - Validate release readiness (tests, linting, version consistency)"
 	@echo "  release-prepare - Prepare release (update versions, build packages)"
+	@echo "  package-check   - Build and validate wheel/sdist with twine"
+	@echo "  publish-gitea   - Publish dist/* to Coulomb Gitea PyPI registry"
 	@echo "  release-test    - Test publication workflow using TestPyPI"
-	@echo "  release-publish - Publish to production PyPI"
+	@echo "  release-publish - Publish to production PyPI (pypi.org)"
 	@echo "  release-finalize - Post-release tasks (tags, GitHub release, documentation)"
 	@echo "  release-rollback - Emergency rollback procedures"
 	@echo ""
@@ -806,7 +812,9 @@ agents-update: $(VENV)/bin/activate
 	@if command -v kaizen-agentic >/dev/null 2>&1; then \
 		kaizen-agentic update; \
 	else \
-		echo "⚠️  kaizen-agentic CLI not found. Install with: pip install kaizen-agentic"; \
+		echo "⚠️  kaizen-agentic CLI not found."; \
+		echo "   Dev install: make agents-install-cli  (or pip install -e .)"; \
+		echo "   Registry: see docs/PACKAGE_RELEASE.md"; \
 	fi

 # Validate installed agents
@@ -815,7 +823,9 @@ agents-validate:
 	@if command -v kaizen-agentic >/dev/null 2>&1; then \
 		kaizen-agentic validate; \
 	else \
-		echo "⚠️  kaizen-agentic CLI not found. Install with: pip install kaizen-agentic"; \
+		echo "⚠️  kaizen-agentic CLI not found."; \
+		echo "   Dev install: make agents-install-cli  (or pip install -e .)"; \
+		echo "   Registry: see docs/PACKAGE_RELEASE.md"; \
 	fi

 # Show agent status and project information
@@ -824,7 +834,9 @@ agents-status:
 	@if command -v kaizen-agentic >/dev/null 2>&1; then \
 		kaizen-agentic status; \
 	else \
-		echo "⚠️  kaizen-agentic CLI not found. Install with: pip install kaizen-agentic"; \
+		echo "⚠️  kaizen-agentic CLI not found."; \
+		echo "   Dev install: make agents-install-cli  (or pip install -e .)"; \
+		echo "   Registry: see docs/PACKAGE_RELEASE.md"; \
 		echo ""; \
 		echo "Manual agent check:"; \
 		if [ -d "agents" ]; then \
@@ -834,6 +846,34 @@ agents-status:
 		fi; \
 	fi

+# Sync canonical agents/ into packaged wheel data
+AGENTS_SRC_DIR = agents
+AGENTS_PKG_DIR = src/kaizen_agentic/data/agents
+
+agents-sync-package:
+	@echo "📦 Syncing packaged agents from $(AGENTS_SRC_DIR)/ ..."
+	@mkdir -p $(AGENTS_PKG_DIR); \
+	SYNCED=0; \
+	for f in $(AGENTS_SRC_DIR)/agent-*.md; do \
+		dest="$(AGENTS_PKG_DIR)/$$(basename $$f)"; \
+		if [ -n "$(DRY_RUN)" ]; then \
+			if [ -f "$$dest" ] && cmp -s "$$f" "$$dest"; then \
+				echo "  = $$(basename $$f) (unchanged)"; \
+			else \
+				echo "  → $$(basename $$f)"; \
+			fi; \
+		else \
+			cp "$$f" "$$dest"; \
+			echo "  ✓ $$(basename $$f)"; \
+			SYNCED=$$((SYNCED + 1)); \
+		fi; \
+	done; \
+	if [ -z "$(DRY_RUN)" ]; then \
+		echo "✅ Synced $$SYNCED file(s) to $(AGENTS_PKG_DIR)/"; \
+	else \
+		echo "ℹ️  DRY_RUN preview only — no files copied"; \
+	fi
+
 # Install agent distribution CLI
 agents-install-cli: $(VENV)/bin/activate
 	@echo "📦 Installing Kaizen Agentic CLI..."
@@ -890,6 +930,21 @@ release-check: $(VENV)/bin/activate
 		echo "    ❌ Build system not configured"; \
 		ISSUES=$$((ISSUES + 1)); \
 	fi; \
+	echo "  • Packaged Agent Parity:"; \
+	PARITY_OK=1; \
+	for f in agents/agent-*.md; do \
+		dest="src/kaizen_agentic/data/agents/$$(basename $$f)"; \
+		if [ ! -f "$$dest" ] || ! cmp -s "$$f" "$$dest"; then \
+			PARITY_OK=0; \
+			break; \
+		fi; \
+	done; \
+	if [ $$PARITY_OK -eq 1 ] && ls agents/agent-*.md >/dev/null 2>&1; then \
+		echo "    ✅ agents/ matches data/agents/"; \
+	else \
+		echo "    ❌ Packaged agents drift from agents/ — run: make agents-sync-package"; \
+		ISSUES=$$((ISSUES + 1)); \
+	fi; \
 	echo ""; \
 	if [ $$ISSUES -eq 0 ]; then \
 		echo "✅ Release readiness: PASSED"; \
@@ -915,8 +970,24 @@ release-prepare: release-check clean
 	ls -la dist/ | grep "$$VERSION" || echo "   • Package files:"; ls -la dist/; \
 	echo ""; \
 	echo "💡 Next steps:"; \
-	echo "   • Run 'make release-test' to test publication"; \
-	echo "   • Run 'make release-publish' for production release"
+	echo "   • Run 'make publish-gitea' for Coulomb Gitea PyPI"; \
+	echo "   • Run 'make release-test' to test publication on TestPyPI"; \
+	echo "   • Run 'make release-publish' for pypi.org (when configured)"
+
+# Build and validate distributions
+package-check: release-prepare
+	$(VENV_PYTHON) -c "import twine" 2>/dev/null || $(VENV_PIP) install twine
+	$(VENV_PYTHON) -m twine check dist/*
+
+# Publish to Coulomb Gitea PyPI registry
+publish-gitea: package-check
+ifndef TWINE_USERNAME
+	$(error TWINE_USERNAME is required (e.g. export TWINE_USERNAME=<gitea-user>))
+endif
+ifndef TWINE_PASSWORD
+	$(error TWINE_PASSWORD is required (e.g. export TWINE_PASSWORD=$$GITEA_API_TOKEN))
+endif
+	$(VENV_PYTHON) -m twine upload --repository-url "$(GITEA_PYPI_REPOSITORY_URL)" dist/*

 # Test publication workflow using TestPyPI
 release-test: release-prepare
@@ -988,7 +1059,8 @@ release-finalize: $(VENV)/bin/activate
 	echo ""; \
 	echo "  • Documentation:"; \
 	echo "    💡 Verify installation instructions work:"; \
-	echo "       pip install kaizen-agentic==$$VERSION"; \
+	echo "       pip install kaizen-agentic==$$VERSION --extra-index-url <gitea-pypi-simple>"; \
+	echo "       See docs/PACKAGE_RELEASE.md"; \
 	echo ""; \
 	echo "✅ Release finalization checklist provided"; \
 	echo "   Complete manual steps above to finish release process"
@@ -1026,4 +1098,4 @@ release-rollback: $(VENV)/bin/activate
 	echo "   • Always test with TestPyPI first"; \
 	echo "   • Use staging/preview environments"; \
 	echo "   • Implement automated quality gates"; \
-	echo "   • Consider pre-release versions for testing"
+	echo "   • Consider pre-release versions for testing"
--- a/README.md
+++ b/README.md
@@ -37,13 +37,21 @@ python3 -m build && make install-local
 source .venv/bin/activate  # Required for each session
 ```

-**From PyPI (Coming Soon):**
+**From Gitea PyPI (v1.1.0+):**
 ```bash
-pip install kaizen-agentic  # Available after v1.0.0 publication
-# or
-pipx install kaizen-agentic  # Recommended for global CLI tools
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
+
+# or global CLI via pipx
+pipx install kaizen-agentic \
+  --pip-args="--extra-index-url https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

+See [docs/PACKAGE_RELEASE.md](docs/PACKAGE_RELEASE.md) for release and CI details.
+
 ### Your First Project (New Users)
 **👋 New to Kaizen Agentic?** Follow our [Hello World Tutorial](docs/HELLO_WORLD_TUTORIAL.md) for a complete step-by-step guide.

--- a/SCOPE.md
+++ b/SCOPE.md
@@ -29,7 +29,8 @@ This repo is the canonical home for the **KaizenAgentic** operating model (`INTE
 - **CLI tooling** (`kaizen-agentic`): `init`, `install`, `update`, `remove`, `list`, `status`, `validate`, `templates`, `detect`, `migrate`, `extensions`, `memory` (show/init/brief/clear), `protocols` (list/show); `metrics` commands planned in WP-0003
 - **Project templates** (python-basic, python-web, python-cli, python-data, comprehensive) — agent bundles in registry code
 - **Python framework** (`src/kaizen_agentic/`): `Agent`/`AgentConfig`, `AgentRegistry`, `AgentInstaller`, `OptimizationLoop`/`PerformanceMetrics`, detection/migration/extensions
- **Packaged agent data** (`src/kaizen_agentic/data/agents/`) — 17 agents bundled for pip installs (lags `agents/` by 4; see Notes)
+- **Packaged agent data** (`src/kaizen_agentic/data/agents/`) — agents bundled for pip installs (sync with `agents/` via `make agents-update`)
+- **Gitea PyPI publication** — `make publish-gitea`, tag-triggered `.gitea/workflows/publish-python-package.yml` (v1.1.0+)
 - **Custodian MCP integration** (owned by `the-custodian`): `list_kaizen_agents()` and `get_kaizen_agent()`
 - **ADRs and workplans** for memory, protocols, workplan, and metrics conventions

@@ -42,7 +43,7 @@ This repo is the canonical home for the **KaizenAgentic** operating model (`INTE
 - Project-specific implementation (agents guide work; they do not build the target software)
 - Custodian State Hub, MCP server code, or cross-domain governance (consumed, not owned)
 - Full KaizenGuidance codemod pipeline (vision in `wiki/KaizenGuidance.md`; not yet implemented)
- PyPI publication pipeline (v1.0.2 released locally; public PyPI distribution still pending)
+- Public pypi.org distribution (optional; Coulomb Gitea registry is primary)

 ---

@@ -68,12 +69,12 @@ This repo is the canonical home for the **KaizenAgentic** operating model (`INTE

 ## Current State

- Status: experimental → stabilizing (v1.0.2; agency framework shipped in WP-0002)
- Strategic layer: `INTENT.md` and `wiki/` established; orientation docs not yet fully linked
- Implementation: substantial — 21 agents, full CLI, agency memory + protocols tested e2e; **measurement loop not closed** (no `.kaizen/metrics/`, optimizer unwired)
- Stability: CLI stable (Click workaround in place); agency framework validated by e2e tests
- Usage: internal dev projects and Custodian MCP hub-wide; packaged wheel missing 4 newest agents
- Active work: **WP-0003** (measurement loop); **WP-0004** (ecosystem integration); WP-0001 (community engagement / v1.1.0) pending
+- Status: stabilizing (v1.1.0 published on Gitea PyPI; WP-0001–0004 completed)
+- Strategic layer: `INTENT.md` and `wiki/` established; ecosystem integration docs in `wiki/EcosystemIntegration.md`
+- Implementation: 20 agents, full CLI (`metrics`, `memory`, `feedback`), agency memory + ADR-004 metrics + optimizer wiring
+- Stability: CLI stable (Click workaround in place); Gitea CI on main; publish workflow on `v*` tags
+- Usage: internal dev projects and Custodian MCP hub-wide; pip install via Gitea extra index
+- Active work: **WP-0005** (adoption polish, fleet parity, publish verification → v1.2.0)

 ---

@@ -162,5 +163,5 @@ keywords: [kaizen, intent, template, optimization, digital-talent-agency]

 ## Notes

- `agents/` (20 files) is the development source of truth; `src/kaizen_agentic/data/agents/` (16 files) is what pip installs ship — coach, sys-medic, scope-analyst, and optimization are not yet bundled
- Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality
+- `agents/` (20 files) is the development source of truth; `src/kaizen_agentic/data/agents/` must stay in sync (enforced in WP-0005 T09–T10)
+- Agent definitions use minimal frontmatter today; full `wiki/KaizenAgentTemplate.md` conformance is a maturity target, not current reality
--- a/TODO.md
+++ b/TODO.md
@@ -10,42 +10,27 @@ The structure organizes **future tasks** by their impact, just as a changelog or

 ## [Unreleased] - *Active Vibe-Coding State* 💡

-Tasks moved to workplan: `workplans/kaizen-agentic-WP-0001-community-engagement.md`
-Hub workstream: `kaizen-wp-0001-community-engagement` (8 tasks, all todo)
+Tasks in workplan: `workplans/kaizen-agentic-WP-0005-adoption-parity.md` (v1.2.0)
+
+### To Add
+* **Gitea publish pipeline verification** — secrets + workflow smoke test
+* **`make agents-sync-package`** — keep `data/agents/` aligned with `agents/`
+* **Install doc sweep** — HELLO_WORLD, CLI_CHEAT_SHEET, AGENT_DISTRIBUTION
+
+### To Refactor
+* **CI lint gate** — flake8 on `src/` in Gitea Actions
+* **Makefile install hints** — point at Gitea registry or dev install
+
+### Deferred to WP-0006 (v1.3.0)
+* Interactive agent selection wizard
+* Agent template schema validation in `validate`
+* Documentation generation from agent metadata

 ***

-## [1.1.0] - Community Engagement and Advanced Automation - *Next Planned Increment*
+## [1.1.0] - Community Engagement — *Shipped 2026-06-18*

-This version focuses on community engagement, advanced automation, and enhanced user experience.
-
-### To Add
-* **Developer feedback mechanisms** for easy collection of user feedback and suggestions
-* **Interactive agent selection** wizard for new projects
-* **GitHub Actions workflows** for CI/CD automation
-* **Agent metrics and telemetry** system for usage tracking and optimization
-* **Agent template validation** system with schema enforcement
-* **Documentation generation** automation from agent metadata
-* **Community contribution guidelines** and contributor onboarding
-
-### To Refactor
-* **CLI error handling** with more user-friendly messages and suggestions
-* **Performance optimization** for handling large numbers of agents
-* **Installation process** with progress indicators and detailed feedback
-
-### To Fix
-* **Cross-platform compatibility** testing and fixes for Windows/macOS environments
-* **Edge case handling** in dependency resolution algorithms
-* **Memory usage optimization** for large-scale agent installations
-
-### To Secure
-* **Agent integrity verification** with checksums and validation
-* **Sandboxed agent execution** for security-sensitive environments
-* **Configuration file validation** to prevent malicious modifications
-
-### To Remove
-* **Legacy installation methods** that are no longer supported
-* **Deprecated CLI options** and maintain backward compatibility warnings
+See `CHANGELOG.md` [1.1.0] and `workplans/kaizen-agentic-WP-0001-community-engagement.md`.

 ***

--- a/agents/agent-code-refactoring.md
+++ b/agents/agent-code-refactoring.md
@@ -169,4 +169,4 @@ The agent focuses on practical, implementable improvements that align with proje
 - Identify and fix security vulnerabilities opportunistically
 - Recommend secure coding practices and patterns
 - Assess input validation and data sanitization
- Evaluate dependency security and update recommendations
+- Evaluate dependency security and update recommendations
--- a/agents/agent-datamodel-optimization.md
+++ b/agents/agent-datamodel-optimization.md
@@ -179,4 +179,4 @@ Based on successful optimizations (e.g., IssueActivity), typical results include

 ---

-*This agent provides systematic datamodel optimization capabilities, ensuring consistent interfaces, reduced code duplication, and improved maintainability across all data structures in the codebase.*
+*This agent provides systematic datamodel optimization capabilities, ensuring consistent interfaces, reduced code duplication, and improved maintainability across all data structures in the codebase.*
--- a/agents/agent-keepaChangelog.md
+++ b/agents/agent-keepaChangelog.md
@@ -284,4 +284,4 @@ When updating or creating changelog files:
 - Indicate urgency of security updates
 - Consider separate security advisory for critical issues

-Remember: Your role is to make version history clear, accessible, and useful for users, maintainers, and stakeholders. Always consider the audience and their need to understand what changed and why it matters.
+Remember: Your role is to make version history clear, accessible, and useful for users, maintainers, and stakeholders. Always consider the audience and their need to understand what changed and why it matters.
--- a/agents/agent-keepaContributingfile.md
+++ b/agents/agent-keepaContributingfile.md
@@ -362,4 +362,4 @@ When updating or creating contributing files:
 - Governance and decision-making processes
 - Release and maintenance responsibilities

-Remember: Your role is to make contributing accessible, clear, and aligned with project goals. Always consider the contributor experience and remove barriers to meaningful participation while maintaining project quality and consistency.
+Remember: Your role is to make contributing accessible, clear, and aligned with project goals. Always consider the contributor experience and remove barriers to meaningful participation while maintaining project quality and consistency.
--- a/agents/agent-keepaTodofile.md
+++ b/agents/agent-keepaTodofile.md
@@ -236,4 +236,4 @@ When updating or creating todo files:
 - Poor priority assessment
 - Missing dependencies or blockers

-Remember: Your role is to make todo management effortless and effective, enabling better focus and productivity. Always consider the human workflow and cognitive load when organizing and presenting tasks.
+Remember: Your role is to make todo management effortless and effective, enabling better focus and productivity. Always consider the human workflow and cognitive load when organizing and presenting tasks.
--- a/agents/agent-optimization.md
+++ b/agents/agent-optimization.md
@@ -188,4 +188,4 @@ kaizen-agentic metrics optimize [agent-name]

 Run without an agent name to analyze all agents with project metrics. Requires
 ≥10 execution records per agent for actionable recommendations (see
-`wiki/AgentKaizenOptimizer.md`).
+`wiki/AgentKaizenOptimizer.md`).
--- a/agents/agent-priority-evaluation.md
+++ b/agents/agent-priority-evaluation.md
@@ -6,10 +6,9 @@ category: project-management

 ## Instructions

-You are the priority assistant helping with project planning and deciding what to do first. 
+You are the priority assistant helping with project planning and deciding what to do first.
 Your goal is to keep in mind the current focus area of tasks and it's relation to the big picture of where we want to go.
 You are responsible for evaluating alternatives to effectively achieving project goals, milestones and the overall mission.
 You look out for important decisions or variants of how to move forward and use weighted shortest job first to score tasks and issues to provide perspective and guidance.

 When asked about a task or issue you establish a wsjf-score and report on the overall score and each dimension to establish it. You supplement this information with additional risk information especially if the decision and resulting implementation might be impossible, hard or expensive to role back.
-
--- a/agents/agent-project-management.md
+++ b/agents/agent-project-management.md
@@ -28,8 +28,8 @@ You are the MarkiTect project assistant, specialized in providing project status
 **Repository Structure:**
 - Main project hosted on Gitea with issue tracking for use cases and tasks
 - Planning documentation goes to roadmap/ROADMAPTOPIC subdirectories
- Closed roadmap-topic-directories git-mv to history/ 
- Auto generated documentation maintained in docs/ 
+- Closed roadmap-topic-directories git-mv to history/
+- Auto generated documentation maintained in docs/
 - Human generated documentation maintained in wiki/ submodule
 - Test-driven development workflow with comprehensive test coverage

@@ -63,7 +63,7 @@ Important: Respect the directory structure! If in doubt ask or use directories u

 When asked about project status or next steps:

-1. **Start with Current State**: Always check TODO.md for the latest activity 
+1. **Start with Current State**: Always check TODO.md for the latest activity
 2. **Review Recent Progress**: Check CHANGELOG.md for previous work and progress
 3. **Check Planned Work**: TODO.md documents next steps and priorities, if empty see topics in roadmap/
 4. **Project Scope and Goals**: Vision, Mission, Guidelines and Usecases live in wiki/ if available
@@ -87,7 +87,7 @@ When asked about project status or next steps:
 - Do NOT implement immediately - issues are for tracking and planning

 **Issue vs. Immediate Work:**
- Current session planned work: document in TODO.md and roadmap/ROADMAPTOPIC 
+- Current session planned work: document in TODO.md and roadmap/ROADMAPTOPIC
 - Discovered improvements: add to workplan in roadmap topic, continue with planned work
 - Critical bugs affecting current work: fix immediately, then create issue for root cause analysis
 - Future enhancements: note in roadmap-topic to create issues first for proper planning
@@ -123,10 +123,10 @@ When asked what's up for a new coding session, follow this standardized routine:
 1. **Mission Status**: Provide reminder to project vision and how we are doing
 2. **Recently**: Provide reminder what we did last from the last entry to the diary
 3. **TODO.md**: Check if we provided guidance for what to do next at the end of the last coding session
-4. **git status**: Check if git is clean or work has been left unfinished 
+4. **git status**: Check if git is clean or work has been left unfinished
 5. **Workspace clean**: Check if workspace is clean or we left of in the middle of a TDD cycle
 6. **Topic or issue finished**: Check if we are currently working on a specific roadmap-topic or issue
-7. **Suggestion**: Provide a sensible suggestion of what to do next 
+7. **Suggestion**: Provide a sensible suggestion of what to do next

 ## Session Wrap-Up Protocol

@@ -170,7 +170,7 @@ Ready for commit: [list of files to commit]
 **Hunch**: Ideas to explore that need consideration if useful and in scope
 **Hickups**: Notes on inefficient or roundtripping implementation to analyse later

-Collect these in the roadmap-topic-directory and move stuff to eat-the-frog on close if unfinished 
+Collect these in the roadmap-topic-directory and move stuff to eat-the-frog on close if unfinished

 ### Example Issue Creation During Development:
 **Scenario**: While implementing CLI commands, discover that error messages could be improved
@@ -178,7 +178,7 @@ Collect these in the roadmap-topic-directory and move stuff to eat-the-frog on c
 **Result**: Continue with current CLI implementation, address error enhancement in future session

 Generate issues for relevantly expensive or risky stuff and in direct feedback with developers.
-Controled in-scope-work does not need the costly issue capture, refinement, selection roundtrip. 
+Controled in-scope-work does not need the costly issue capture, refinement, selection roundtrip.

 Remember: Your role is to help developers quickly understand "where we are" and "what should we do next" when picking up work on the MarkiTect project, and to ensure proper session wrap-up for continuity.

--- a/agents/agent-releaseManager.md
+++ b/agents/agent-releaseManager.md
@@ -98,4 +98,4 @@ When managing releases, always prioritize:
 1. **Security**: Never compromise on security practices
 2. **Reliability**: Thorough testing before publication
 3. **Communication**: Clear documentation and announcements
-4. **Reproducibility**: Consistent and documented processes
+4. **Reproducibility**: Consistent and documented processes
--- a/agents/agent-requirements-engineering.md
+++ b/agents/agent-requirements-engineering.md
@@ -499,4 +499,4 @@ The agent directly addresses the root causes:

 ---

-*This agent provides systematic foundation analysis and interface contract verification based on lessons learned from Issue #59 to prevent compatibility issues and ensure solid architectural foundations before implementation.*
+*This agent provides systematic foundation analysis and interface contract verification based on lessons learned from Issue #59 to prevent compatibility issues and ensure solid architectural foundations before implementation.*
--- a/agents/agent-setupRepository.md
+++ b/agents/agent-setupRepository.md
@@ -412,4 +412,4 @@ When setting up or checking repositories, always verify that:
 - Standards compliance is treated as a required test, not optional check
 - Missing .gitignore or other essential files will be caught automatically

-Remember: Your role is to transform repository stubs into production-ready Python projects that follow industry best practices, enable efficient development workflows, and provide a solid foundation for long-term project success.
+Remember: Your role is to transform repository stubs into production-ready Python projects that follow industry best practices, enable efficient development workflows, and provide a solid foundation for long-term project success.
--- a/agents/agent-tdd-workflow.md
+++ b/agents/agent-tdd-workflow.md
@@ -143,7 +143,7 @@ You understand the workspace structure (default: `.tddai_workspace/`, configurab
 - `DIRTY` - Workspace directory exists but no current issue file

 ### Test Development Best Practices
-**Test Naming Convention:** 
+**Test Naming Convention:**
 - `test_{capability}_issue_{NUM}_{scenario}.py`

 **Required Test Structure:**
--- a/agents/agent-test-maintenance.md
+++ b/agents/agent-test-maintenance.md
@@ -141,4 +141,4 @@ ACTION: Change import path, verify test logic still valid
 - **Communicate trade-offs** when removing functionality
 - **Maintain backward compatibility** where feasible

-This agent ensures the MarkiTect project maintains a robust, reliable test suite that accurately reflects the current codebase architecture and functionality.
+This agent ensures the MarkiTect project maintains a robust, reliable test suite that accurately reflects the current codebase architecture and functionality.
--- a/agents/agent-testing-efficiency.md
+++ b/agents/agent-testing-efficiency.md
@@ -291,4 +291,4 @@ markers =

 ---

-*This agent provides specialized test execution optimization focused on TDD8 workflow enhancement, pytest reliability resolution, and systematic testing efficiency improvements for development velocity.*
+*This agent provides specialized test execution optimization focused on TDD8 workflow enhancement, pytest reliability resolution, and systematic testing efficiency improvements for development velocity.*
--- a/agents/agent-tooling-optimization.md
+++ b/agents/agent-tooling-optimization.md
@@ -196,4 +196,4 @@ RECOMMENDATION: Suggest primary tools and deprecation plan for others
 IMPLEMENTATION: Provide migration guide and updated documentation
 ```

-This agent ensures the MarkiTect project maintains an optimized, efficient tooling ecosystem that maximizes developer productivity and minimizes friction in development workflows.
+This agent ensures the MarkiTect project maintains an optimized, efficient tooling ecosystem that maximizes developer productivity and minimizes friction in development workflows.
--- a/docs/AGENT_DISTRIBUTION.md
+++ b/docs/AGENT_DISTRIBUTION.md
@@ -13,13 +13,18 @@ The Kaizen Agentic framework provides a comprehensive system for distributing an

 ## Installation

-Install the Kaizen Agentic package:
+Install the Kaizen Agentic package from the Coulomb Gitea PyPI registry:

 ```bash
-pip install kaizen-agentic
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

-This provides the `kaizen-agentic` CLI tool for managing agents.
+This provides the `kaizen-agentic` CLI tool for managing agents. See
+[PACKAGE_RELEASE.md](PACKAGE_RELEASE.md) for pipx, local builds, and publishing.

 ## CLI Commands

@@ -373,10 +378,7 @@ If you're currently managing agents manually:
   ls agents/agent-*.md
   ```

-2. **Install Package**:
-   ```bash
-   pip install kaizen-agentic
-   ```
+2. **Install Package** (same as Installation section above).

 3. **Validate Current Setup**:
   ```bash
@@ -412,4 +414,4 @@ When updating Kaizen Agentic versions:
   kaizen-agentic validate
   ```

-This distribution system makes it easy to share and maintain consistent development workflows across all your projects using specialized AI agents.
+This distribution system makes it easy to share and maintain consistent development workflows across all your projects using specialized AI agents.
--- a/docs/CLI_CHEAT_SHEET.md
+++ b/docs/CLI_CHEAT_SHEET.md
@@ -3,8 +3,15 @@
 Quick reference for the `kaizen-agentic` command-line tool.

 ## Installation
+
+From Coulomb Gitea PyPI (see [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md)):
+
 ```bash
-pip install kaizen-agentic
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

 ## Core Commands
@@ -125,7 +132,7 @@ kaizen-agentic status
 ```bash
 git clone team-repo
 cd team-repo
-pip install kaizen-agentic
+# Install CLI — see Installation section above
 kaizen-agentic status        # See what agents are used
 cat CLAUDE.md               # Read agent documentation
 ```
@@ -185,8 +192,7 @@ make agents-status    # Show detailed status

 ### Common Issues
 ```bash
-# Command not found
-pip install kaizen-agentic
+# Command not found — reinstall (see Installation section)

 # No agents directory
 kaizen-agentic install todo-keeper
@@ -227,4 +233,4 @@ kaizen-agentic update && kaizen-agentic validate
 ```bash
 kaizen-agentic status
 cat CLAUDE.md  # Detailed info
-```
+```
--- a/docs/GETTING_STARTED.md
+++ b/docs/GETTING_STARTED.md
@@ -57,16 +57,22 @@ make install-global
 # CLI available from any directory
 ```

-**Option D: From PyPI (Coming Soon)**
+**Option D: From Gitea PyPI (v1.1.0+)**

 ```bash
-# Will be available once v1.0.0 is published
-pip install kaizen-agentic
-# or
-pipx install kaizen-agentic  # Recommended for global CLI tools
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
+
+# or global CLI via pipx
+pipx install kaizen-agentic \
+  --pip-args="--extra-index-url https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

-> **📦 Release Status**: v1.0.0 is ready for publication. Use `make install-global` for system-wide availability.
+> **📦 Registry**: Published on the Coulomb Gitea PyPI registry. Dependencies resolve
+> from public PyPI via `--extra-index-url`. See [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md).

 ### 2. Verify Installation

@@ -265,7 +271,9 @@ jobs:
      - uses: actions/setup-python@v4
        with:
          python-version: '3.8'
-      - run: pip install kaizen-agentic
+      - run: >-
+          pip install kaizen-agentic
+          --extra-index-url "https://${{ secrets.GITEA_PACKAGE_USER }}:${{ secrets.GITEA_PACKAGE_TOKEN }}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
      - run: kaizen-agentic validate
 ```

@@ -405,7 +413,8 @@ kaizen-agentic status
 # New team member setup
 git clone project-repo
 cd project-repo
-pip install kaizen-agentic  # or add to requirements
+# see Option D for GITEA_PACKAGE_USER / GITEA_PACKAGE_TOKEN and --extra-index-url
+pip install kaizen-agentic
 kaizen-agentic status       # See what agents are used
 kaizen-agentic validate     # Verify everything works

@@ -419,12 +428,16 @@ cat CLAUDE.md

 **"Command not found: kaizen-agentic"**
 ```bash
-# Install the package
-pip install kaizen-agentic
+# Install from Gitea PyPI (same credentials as Option D)
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"

 # Or if using virtual env:
 source .venv/bin/activate
-pip install kaizen-agentic
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

 **"No agents directory found"**
@@ -463,4 +476,4 @@ Once you have agents installed:
 4. **Share with team**: Document which agents your project uses
 5. **Contribute back**: Report issues and suggest improvements

-The key insight is that **you don't need the Makefile targets to use agents effectively** - the `kaizen-agentic` CLI provides all the functionality you need. The Makefile targets are just convenient shortcuts for projects that have them.
+The key insight is that **you don't need the Makefile targets to use agents effectively** - the `kaizen-agentic` CLI provides all the functionality you need. The Makefile targets are just convenient shortcuts for projects that have them.
--- a/docs/HELLO_WORLD_TUTORIAL.md
+++ b/docs/HELLO_WORLD_TUTORIAL.md
@@ -9,10 +9,18 @@ This step-by-step tutorial will guide you through creating your first project wi

 ## Step 1: Install Kaizen Agentic

+From the Coulomb Gitea PyPI registry (dependencies resolve from public PyPI):
+
 ```bash
-pip install kaizen-agentic
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

+See [PACKAGE_RELEASE.md](PACKAGE_RELEASE.md) for pipx and release details.
+
 Verify the installation:

 ```bash
@@ -235,7 +243,11 @@ kaizen-agentic status

 **"kaizen-agentic: command not found"**
 ```bash
-pip install kaizen-agentic
+# Same install as Step 1 (Gitea extra index — see PACKAGE_RELEASE.md)
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
 ```

 **"make: command not found"**
@@ -267,4 +279,4 @@ make test
 - ✅ AI agents for development assistance
 - ✅ Make-based development commands

-You're now ready to build amazing Python projects with AI agent assistance! 🚀
+You're now ready to build amazing Python projects with AI agent assistance! 🚀
--- a/docs/INTEGRATION_PATTERNS.md
+++ b/docs/INTEGRATION_PATTERNS.md
@@ -39,12 +39,26 @@ invoke kaizen-agentic CLI commands.
 | [post-install-metrics-scaffold](integrations/activity-definitions/post-install-metrics-scaffold.md) | `kaizen.agent.installed` | `memory init` validation |
 | [low-success-rate-review](integrations/activity-definitions/low-success-rate-review.md) | `kaizen.metrics.recorded` | `metrics show` + `optimize` |

-**Activation:**
+**Activation handoff (activity-core owners):**

-1. Copy or symlink definitions from `docs/integrations/activity-definitions/` into
-   activity-core's `activity-definitions/` tree (or register as external ConfigMap).
-2. Run `make sync-activity-definitions` in activity-core.
-3. Enable definitions (`enabled: true`) after resolver wiring is verified.
+1. **Copy definitions** from kaizen-agentic:
+   `docs/integrations/activity-definitions/*.md` → activity-core
+   `activity-definitions/kaizen-agentic/` (or org-equivalent path per ACT-ADR-002).
+2. **Register in activity-core index** — ensure each definition slug appears in the
+   activity-core catalog consumed by the resolver.
+3. **Run sync** in activity-core: `make sync-activity-definitions` (or repo-equivalent).
+4. **Wire triggers** — map cron / NATS subjects (`kaizen.agent.installed`,
+   `kaizen.metrics.recorded`) to the documented CLI invocations.
+5. **Enable gradually** — set `enabled: true` per definition after a manual smoke test
+   against a repo with `.kaizen/metrics/` populated.
+6. **Verify credentials** — scheduled runs need `kaizen-agentic` on PATH and any
+   Gitea PyPI extra index if the runner installs from registry (see PACKAGE_RELEASE.md).
+
+**kaizen-agentic maintainer checklist:**
+
+- [ ] Three definition files committed under `docs/integrations/activity-definitions/`
+- [ ] activity-core PR or issue opened to register definitions
+- [ ] Smoke test commands documented below pass on a pilot repo

 **Smoke test (manual):**

@@ -102,4 +116,4 @@ No runtime dependency in WP-0004.
 | `HELIX_TOKENS`, `HELIX_INFRA_OVERHEAD_SHARE` | `metrics record` | Fleet cost fields |
 | `HELIX_STORE_DB` | `metrics correlate` | Digest lookup database |
 | `ARTIFACTSTORE_API_URL` | `metrics publish` | Registry endpoint |
-| `ARTIFACTSTORE_API_TOKEN` | `metrics publish` | Write auth bearer token |
+| `ARTIFACTSTORE_API_TOKEN` | `metrics publish` | Write auth bearer token |
--- a/docs/PACKAGE_RELEASE.md
+++ b/docs/PACKAGE_RELEASE.md
@@ -0,0 +1,115 @@
+# Python Package Release
+
+`kaizen-agentic` publishes as the `kaizen-agentic` Python package on the Coulomb
+Gitea PyPI registry. Public [pypi.org](https://pypi.org/) distribution is optional
+and not required for ecosystem use.
+
+## Install (consumers)
+
+Dependencies such as `pyyaml` resolve from public PyPI. Use Gitea as an extra index:
+
+```bash
+export GITEA_PACKAGE_USER=<gitea-user>
+export GITEA_PACKAGE_TOKEN=<package-token>
+
+pip install kaizen-agentic \
+  --extra-index-url "https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
+```
+
+Global CLI via pipx:
+
+```bash
+pipx install kaizen-agentic \
+  --pip-args="--extra-index-url https://${GITEA_PACKAGE_USER}:${GITEA_PACKAGE_TOKEN}@gitea.coulomb.social/api/packages/coulomb/pypi/simple/"
+```
+
+Do not commit tokenized index URLs. Inject credentials via environment variables or
+CI secrets.
+
+## Local Release
+
+Build and validate artifacts:
+
+```bash
+make package-check
+```
+
+Publish to the Coulomb organization registry:
+
+```bash
+TWINE_USERNAME=<gitea-user> \
+TWINE_PASSWORD=<package-token> \
+make publish-gitea
+```
+
+Package upload endpoint:
+
+```text
+https://gitea.coulomb.social/api/packages/coulomb/pypi
+```
+
+Consumer simple index:
+
+```text
+https://gitea.coulomb.social/api/packages/coulomb/pypi/simple/
+```
+
+## Gitea repository secrets (one-time)
+
+Configure in Gitea: **Repository → Settings → Actions → Secrets**.
+
+| Secret | Value |
+|--------|-------|
+| `PACKAGE_USER` | Gitea username with package upload permission (e.g. `tegwick`) |
+| `PACKAGE_TOKEN` | Gitea API token with `write:package` scope |
+
+Gitea rejects secret names prefixed with `GITEA_` — use `PACKAGE_USER` / `PACKAGE_TOKEN`
+(not `GITEA_PACKAGE_USER`). Workflows use `runs-on: haskelseed` and native `git clone`
+(no GitHub Marketplace actions).
+
+The publish workflow fails at the upload step when either secret is missing or
+invalid. Do not commit tokens to the repository.
+
+Verify secrets without cutting a release:
+
+1. Open **Actions → Publish Python package → Run workflow** (`workflow_dispatch`),
+   or dispatch via API:
+   `POST /api/v1/repos/coulomb/kaizen-agentic/actions/workflows/publish-python-package.yml/dispatches`
+   with body `{"ref":"main"}`
+2. Confirm the run completes and `twine upload` succeeds
+3. Optional: `pip install kaizen-agentic==<version> --extra-index-url ...`
+
+The publish job uses an isolated `.build-venv` on the runner (PEP 668 safe).
+
+## Pre-tag release checklist
+
+Before `git tag vX.Y.Z && git push origin vX.Y.Z`:
+
+- [ ] `make release-check` passes (tests, flake8, version consistency, agent parity)
+- [ ] `make package-check` builds and validates `dist/*`
+- [ ] `CHANGELOG.md` has a dated `[X.Y.Z]` section matching `pyproject.toml`
+- [ ] `PACKAGE_USER` and `PACKAGE_TOKEN` secrets are set
+- [ ] Publish workflow smoke-tested via `workflow_dispatch` (or prior tag release)
+- [ ] `make agents-sync-package` run if `agents/` changed since last release
+
+## Gitea Actions Release
+
+The `.gitea/workflows/publish-python-package.yml` workflow publishes on tags
+matching `v*`.
+
+Example:
+
+```bash
+git tag v1.2.0
+git push origin v1.2.0
+```
+
+## Public PyPI (optional)
+
+When pypi.org credentials are configured (`~/.pypirc` or `TWINE_PASSWORD` API
+token with `TWINE_USERNAME=__token__`):
+
+```bash
+make release-publish
+python -m twine upload dist/*
+```
--- a/docs/integrations/helix-forge-correlation.md
+++ b/docs/integrations/helix-forge-correlation.md
@@ -93,11 +93,11 @@ documenting expected fields — no ingestion code runs in kaizen-agentic.
 | [DESIGN-session-memory.md](https://github.com/coulomb/agentic-resources/blob/main/docs/DESIGN-session-memory.md) | agentic-resources |
 | `session_memory/core/store.py` — `get_digest()` | agentic-resources |

-agentic-resources should link back to this document from its session-memory design
-notes when documenting downstream consumers of `session_uid`.
+**Reciprocal link status:** verified (WP-0005 T16). `agentic-resources/docs/DESIGN-session-memory.md`
+§11 cites this document and ADR-004.

 ## Non-goals

 - No Claude/Codex/Grok JSONL ingestion in kaizen-agentic
 - No write path to Helix Forge from kaizen-agentic CLI
- No merge of fleet baselines into project `summary.json` (Coach may cite both)
+- No merge of fleet baselines into project `summary.json` (Coach may cite both)
--- a/src/kaizen_agentic/data/agents/agent-claude-documentation.md
+++ b/src/kaizen_agentic/data/agents/agent-claude-documentation.md
@@ -1,6 +1,7 @@
 ---
-name: claude-expert
+name: claude-documentation
 description: Specialized assistant for Claude and Claude Code documentation, features, and best practices
+category: documentation
 ---

 ## Instructions
--- a/src/kaizen_agentic/data/agents/agent-code-refactoring.md
+++ b/src/kaizen_agentic/data/agents/agent-code-refactoring.md
@@ -1,7 +1,8 @@
 ---
-name: refactoring-assistant
+name: code-refactoring
 description: Analyze code structure and quality, identify improvement opportunities, and provide actionable refactoring guidance. Use PROACTIVELY for code quality assessment and improvement.
 model: inherit
+category: code-quality
 ---

 # Refactoring Assistant - Code Structure and Quality Improvement Agent
@@ -168,4 +169,4 @@ The agent focuses on practical, implementable improvements that align with proje
 - Identify and fix security vulnerabilities opportunistically
 - Recommend secure coding practices and patterns
 - Assess input validation and data sanitization
- Evaluate dependency security and update recommendations
+- Evaluate dependency security and update recommendations
--- a/src/kaizen_agentic/data/agents/agent-datamodel-optimization.md
+++ b/src/kaizen_agentic/data/agents/agent-datamodel-optimization.md
@@ -1,7 +1,8 @@
 ---
-name: datamodel-optimizer
+name: datamodel-optimization
 description: Specialized agent that systematically analyzes, optimizes, and enhances dataclasses, models, and data structures within a codebase. Provides comprehensive datamodel improvements including convenience methods, interface consistency, code reduction, and test alignment.
 model: inherit
+category: code-quality
 ---

 # Datamodel Optimization Specialist Agent
@@ -178,4 +179,4 @@ Based on successful optimizations (e.g., IssueActivity), typical results include

 ---

-*This agent provides systematic datamodel optimization capabilities, ensuring consistent interfaces, reduced code duplication, and improved maintainability across all data structures in the codebase.*
+*This agent provides systematic datamodel optimization capabilities, ensuring consistent interfaces, reduced code duplication, and improved maintainability across all data structures in the codebase.*
--- a/src/kaizen_agentic/data/agents/agent-keepaChangelog.md
+++ b/src/kaizen_agentic/data/agents/agent-keepaChangelog.md
@@ -1,6 +1,7 @@
 ---
-name: changelog-keeper
+name: keepaChangelog
 description: Specialized assistant for maintaining CHANGELOG.md files following Keep a Changelog format
+category: project-management
 ---

 ## Instructions
@@ -283,4 +284,4 @@ When updating or creating changelog files:
 - Indicate urgency of security updates
 - Consider separate security advisory for critical issues

-Remember: Your role is to make version history clear, accessible, and useful for users, maintainers, and stakeholders. Always consider the audience and their need to understand what changed and why it matters.
+Remember: Your role is to make version history clear, accessible, and useful for users, maintainers, and stakeholders. Always consider the audience and their need to understand what changed and why it matters.
--- a/src/kaizen_agentic/data/agents/agent-keepaContributingfile.md
+++ b/src/kaizen_agentic/data/agents/agent-keepaContributingfile.md
@@ -1,6 +1,7 @@
 ---
-name: contributing-keeper
+name: keepaContributingfile
 description: Specialized assistant for maintaining CONTRIBUTING.md files following Keep a Contributing-File V0.0.1 format within the Kaizen Agentic framework
+category: documentation
 ---

 ## Instructions
@@ -63,7 +64,9 @@ This repository is a sophisticated AI agent development framework with unique ch
 ```markdown
 # Contributing

-This document outlines how to get started, how we organize work, and how to help maintain the quality & clarity of our contributions.
+This is a "how to contribute" file, useful to orient yourself to help not hinder this project to progress.
+
+The format is based on [Keep a Contributingfile V0.0.1](https://coulomb.social/open/ContributingFileGuide).

 *Thank you for your interest in contributing!*

@@ -359,4 +362,4 @@ When updating or creating contributing files:
 - Governance and decision-making processes
 - Release and maintenance responsibilities

-Remember: Your role is to make contributing accessible, clear, and aligned with project goals. Always consider the contributor experience and remove barriers to meaningful participation while maintaining project quality and consistency.
+Remember: Your role is to make contributing accessible, clear, and aligned with project goals. Always consider the contributor experience and remove barriers to meaningful participation while maintaining project quality and consistency.
--- a/src/kaizen_agentic/data/agents/agent-keepaTodofile.md
+++ b/src/kaizen_agentic/data/agents/agent-keepaTodofile.md
@@ -1,6 +1,7 @@
 ---
-name: todo-keeper
+name: keepaTodofile
 description: Specialized assistant for maintaining TODO.md files following Keep a Todofile V0.0.1 format
+category: project-management
 ---

 ## Instructions
@@ -42,7 +43,7 @@ You have explicit authority to:

 This is a "to do next" file, particularly useful to keep the human and a coding assistant in sync.

-The format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/KeepaTodofile).
+The format is based on [Keep a Todofile V0.0.1](https://coulomb.social/open/TodoFileGuide).

 The structure organizes **future tasks** by their impact, just as a changelog organizes past changes by their impact.

@@ -235,4 +236,4 @@ When updating or creating todo files:
 - Poor priority assessment
 - Missing dependencies or blockers

-Remember: Your role is to make todo management effortless and effective, enabling better focus and productivity. Always consider the human workflow and cognitive load when organizing and presenting tasks.
+Remember: Your role is to make todo management effortless and effective, enabling better focus and productivity. Always consider the human workflow and cognitive load when organizing and presenting tasks.
--- a/src/kaizen_agentic/data/agents/agent-optimization.md
+++ b/src/kaizen_agentic/data/agents/agent-optimization.md
@@ -188,4 +188,4 @@ kaizen-agentic metrics optimize [agent-name]

 Run without an agent name to analyze all agents with project metrics. Requires
 ≥10 execution records per agent for actionable recommendations (see
-`wiki/AgentKaizenOptimizer.md`).
+`wiki/AgentKaizenOptimizer.md`).
--- a/src/kaizen_agentic/data/agents/agent-priority-evaluation.md
+++ b/src/kaizen_agentic/data/agents/agent-priority-evaluation.md
@@ -1,14 +1,14 @@
 ---
-name: priority-assistant
-description: Specialized assistant to help evaluate and establish priorities for issues and tasks. 
+name: priority-evaluation
+description: Specialized assistant to help evaluate and establish priorities for issues and tasks.
+category: project-management
 ---

 ## Instructions

-You are the priority assistant helping with project planning and deciding what to do first. 
+You are the priority assistant helping with project planning and deciding what to do first.
 Your goal is to keep in mind the current focus area of tasks and it's relation to the big picture of where we want to go.
 You are responsible for evaluating alternatives to effectively achieving project goals, milestones and the overall mission.
 You look out for important decisions or variants of how to move forward and use weighted shortest job first to score tasks and issues to provide perspective and guidance.

 When asked about a task or issue you establish a wsjf-score and report on the overall score and each dimension to establish it. You supplement this information with additional risk information especially if the decision and resulting implementation might be impossible, hard or expensive to role back.
-
--- a/src/kaizen_agentic/data/agents/agent-project-management.md
+++ b/src/kaizen_agentic/data/agents/agent-project-management.md
@@ -1,6 +1,7 @@
 ---
 name: project-assistant
 description: Specialized assistant for project status, progress tracking, and development planning
+category: project-management
 ---

 ## Instructions
@@ -15,24 +16,37 @@ You are the MarkiTect project assistant, specialized in providing project status

 ### Key Project Files & Their Purpose

- **ProjectStatusDigest.md**: The canonical source of truth for project architecture, features, and current state
- **ProjectDiary.md**: Chronological record of major work packages, milestones, and development sessions
- **NEXT.md**: Next steps and priorities to ease transfer between coding sessions
+- **TODO.md**: Current state of implemenation based on the Keep-A-Todofile format for maintaining coding flow
+- **CHANGELOG.md**: History of releases based on the Keep-A-Changelog format for easy access to what happend before
+- **roadmap/**: Directory with current and close range roadmap-topic-directories for concepts, workplans, examples...
+- **history/**: Directory with closed roadmap-topic-directories including finishd TODO.md files as YYMMDD-DONE.md
 - **Makefile**: Provides helpers to use and improve the capabilities provided by the project
-  **Gitea Issues**: Backlog of issues and backlog of tasks stored as issues in gitea
+  **Gitea Issues**: Backlog of issues and backlog of tasks stored as issues in gitea before selection as roadmap topics

 ### Project Infrastructure Knowledge

 **Repository Structure:**
 - Main project hosted on Gitea with issue tracking for use cases and tasks
- Documentation maintained in `wiki/` submodule
- Test-drive dev workflow with tests in `tests/` handled by tddai-assistent subagent
+- Planning documentation goes to roadmap/ROADMAPTOPIC subdirectories
+- Closed roadmap-topic-directories git-mv to history/
+- Auto generated documentation maintained in docs/
+- Human generated documentation maintained in wiki/ submodule
+- Test-driven development workflow with comprehensive test coverage
+
+Important: Respect the directory structure! If in doubt ask or use directories under tmp/ to keep the structure clean!

 **Development Workflow:**
 - Issue-driven development using Gitea API integration
- TDD8 methodology via tddai-assistant subagent for comprehensive test-driven development
+- Issue management via universal issue-facade CLI that works with multiple backends
 - All commits require green test state

+**Capability Inclusion Management:**
+- **Internal Capabilities**: See `CAPABILITIES.md` for what MarkiTect provides to the world
+- **External Capabilities**: Check `CAPABILITY_REGISTRY.md` for what MarkiTect uses
+- **Before implementing**: Use `CLAUDE_CAPABILITY_REFERENCE.md` for quick lookup
+- **Architecture Guide**: See `CAPABILITY_INCLUSION_GUIDE.md` for complete workflow
+- **Discovery Tools**: `make capability-search TERM=xyz` to find existing functionality
+
 **Issue Management Protocol:**
 - **Gitea-First**: Feature requests, bugs, and enhancements should be documented as Gitea issues
 - **Issue Creation**: When new requirements emerge, create issues in Gitea immediately but do NOT implement immediately
@@ -41,25 +55,27 @@ You are the MarkiTect project assistant, specialized in providing project status
 - **Issue Workflow**: Create → Triage → Plan → Schedule → Implement → Close

 **TDD Workflow Management:**
- For all TDD-related guidance, workflow management, and test-driven development questions, use the **tddai-assistant** subagent
- The tddai-assistant specializes in the TDD8 methodology (ISSUE-TEST-RED-GREEN-REFACTOR-DOCUMENT-REFINE-PUBLISH cycle)
+- For issue management tasks, use the **issue-facade** system located in `capabilities/issue-facade/`
+- The issue-facade provides unified CLI for GitHub, GitLab, Gitea, and local SQLite backends
 - This includes sidequest management, test planning, and comprehensive development workflow guidance

 ### Response Guidelines

 When asked about project status or next steps:

-1. **Start with Current State**: Always check ProjectStatusDigest.md for the latest architecture and status
-2. **Review Recent Progress**: Check ProjectDiary.md for recent accomplishments and context
-3. **Check Planned Work**: Read Next.md for documented next steps and priorities
-4. **Consider Git Status**: Be aware of current working directory state and recent commits
+1. **Start with Current State**: Always check TODO.md for the latest activity
+2. **Review Recent Progress**: Check CHANGELOG.md for previous work and progress
+3. **Check Planned Work**: TODO.md documents next steps and priorities, if empty see topics in roadmap/
+4. **Project Scope and Goals**: Vision, Mission, Guidelines and Usecases live in wiki/ if available
+5. **Planning New Stuff**: Requirements (Epics and Stories) are gitea issues to be planned as roadmap topics
+6. **Consider Git Status**: Allways be aware of current working directory state and recent commits

 ### Issue Management Guidelines

 **When to Create Gitea Issues:**
 - New feature requests or enhancement ideas emerge during development
 - Bugs or technical debt are discovered but not immediately fixable
- Future improvements are identified but outside current session scope
+- Future improvements are identified but outside current session and topic scope
 - Architecture decisions require documentation and future review
 - Sidequests that we want to remember for later implementation

@@ -71,10 +87,12 @@ When asked about project status or next steps:
 - Do NOT implement immediately - issues are for tracking and planning

 **Issue vs. Immediate Work:**
- Current session planned work: implement directly (from Next.md)
- Discovered improvements: create issue, continue with planned work
+- Current session planned work: document in TODO.md and roadmap/ROADMAPTOPIC
+- Discovered improvements: add to workplan in roadmap topic, continue with planned work
 - Critical bugs affecting current work: fix immediately, then create issue for root cause analysis
- Future enhancements: always create issue first for proper planning
+- Future enhancements: note in roadmap-topic to create issues first for proper planning
+- If possible create issues interactively when closing a topic, they are for human oversight and longterm
+- Do not create issues for stuff that is detailed and can be adressed before closing the current topic

 **Response Format:**
 - Provide a brief status summary (2-3 sentences)
@@ -95,8 +113,6 @@ When asked about project status or next steps:
 1. [Action from Next.md or logical progression]
 2. [Secondary priority or alternative approach]
 3. [Maintenance or validation task if applicable]
-
-Based on: ProjectStatusDigest.md:74-79, Next.md:7-13
 ```

 ## Session Start-Up Protocol
@@ -106,22 +122,21 @@ When asked what's up for a new coding session, follow this standardized routine:
 ### Start-of-Session Checklist
 1. **Mission Status**: Provide reminder to project vision and how we are doing
 2. **Recently**: Provide reminder what we did last from the last entry to the diary
-3. **NEXT.txt**: Check if we provided guidance for what to do next at the end of the last coding session
-4. **git status**: Check if git is clean or work has been left unfinished 
+3. **TODO.md**: Check if we provided guidance for what to do next at the end of the last coding session
+4. **git status**: Check if git is clean or work has been left unfinished
 5. **Workspace clean**: Check if workspace is clean or we left of in the middle of a TDD cycle
-6. **Issue finished**: Check if we are currently working on a specific issue or need to select the next one
-7. **Suggestion**: Provide a sensible suggestion of what to do next 
+6. **Topic or issue finished**: Check if we are currently working on a specific roadmap-topic or issue
+7. **Suggestion**: Provide a sensible suggestion of what to do next

 ## Session Wrap-Up Protocol

 When asked to help wrap up a development session, follow this standardized routine:

 ### End-of-Session Checklist:
-1. **Update ProjectDiary.md**: Add entry documenting progress, challenges, and achievements
-2. **Update NEXT.md**: Set clear priorities and strategy for next session
-3. **Update ProjectStatusDigest.md**: Refresh current status, metrics, and completed features
+2. **Update TODO.md**: Set clear priorities and strategy for next session using todofile format
+3. **Update roadmap-topic directory information**: Refresh current status, metrics, and completed features
 4. **Issue Management**: Review and create any issues for sidequests and discoveries made during session
-5. **Anchor patterns**: Update this project-assistant definition with any new workflow patterns
+5. **Anchor patterns**: Add Update suggestions for this project-assistant definition with any new workflow patterns
 6. **Prepare for commit**: Ensure all documentation reflects current state

 ### Session Success Indicators:
@@ -136,9 +151,9 @@ When asked to help wrap up a development session, follow this standardized routi
 [Brief overview of accomplishments and current state]

 ## Documentation Updates
- ✅ ProjectDiary.md: [what was added]
- ✅ Next.md: [priorities set]
- ✅ ProjectStatusDigest.md: [status updated]
+- ✅ TODO.md: [priorities set]
+- ✅ roadmap/TOPIC files: [what was added or changed]
+- ✅ CHANGELOG.ms: [status updated especially on release]

 ## Issues Created/Updated
 - 🎯 Issue #X: [brief description] - [reason for creation]
@@ -150,9 +165,33 @@ When asked to help wrap up a development session, follow this standardized routi
 Ready for commit: [list of files to commit]
 ```

+### Example Capture Small Off-Topic Improvements in roadmap/eat-the-frog:
+**Smell**: Different filename conventions od conflicting concepts, unclear guideance
+**Hunch**: Ideas to explore that need consideration if useful and in scope
+**Hickups**: Notes on inefficient or roundtripping implementation to analyse later
+
+Collect these in the roadmap-topic-directory and move stuff to eat-the-frog on close if unfinished
+
 ### Example Issue Creation During Development:
 **Scenario**: While implementing CLI commands, discover that error messages could be improved
 **Action**: Create issue "Enhance CLI error messages with user-friendly formatting and suggestions"
 **Result**: Continue with current CLI implementation, address error enhancement in future session

+Generate issues for relevantly expensive or risky stuff and in direct feedback with developers.
+Controled in-scope-work does not need the costly issue capture, refinement, selection roundtrip.
+
 Remember: Your role is to help developers quickly understand "where we are" and "what should we do next" when picking up work on the MarkiTect project, and to ensure proper session wrap-up for continuity.
+
+---
+
+## Session Start
+
+1. Check for `.kaizen/agents/project-management/memory.md` in the project root.
+2. If present, read it and surface relevant context (last session summary, open threads, watch points) in your opening brief.
+3. If absent, offer to initialise with `kaizen-agentic memory init project-management`.
+
+## Session Close
+
+1. Update `## Accumulated Findings`, `## What Worked`, `## Watch Points` based on this session.
+2. Append one line to `## Session Log`: `YYYY-MM-DD · <brief summary> · <outcome>`.
+3. Bump `last_updated` to today and increment `session_count`.
--- a/src/kaizen_agentic/data/agents/agent-releaseManager.md
+++ b/src/kaizen_agentic/data/agents/agent-releaseManager.md
@@ -98,4 +98,4 @@ When managing releases, always prioritize:
 1. **Security**: Never compromise on security practices
 2. **Reliability**: Thorough testing before publication
 3. **Communication**: Clear documentation and announcements
-4. **Reproducibility**: Consistent and documented processes
+4. **Reproducibility**: Consistent and documented processes
--- a/src/kaizen_agentic/data/agents/agent-requirements-engineering.md
+++ b/src/kaizen_agentic/data/agents/agent-requirements-engineering.md
@@ -1,7 +1,8 @@
 ---
-name: requirements-engineering-agent
+name: requirements-engineering
 description: Specialized agent designed to prevent interface compatibility issues and mock object mismatches by ensuring solid foundation planning before implementation. Based on lessons learned from Issue #59, provides practical toolkit commands and enhanced TDD8 workflow integration to catch interface problems before implementation.
 model: inherit
+category: development-process
 ---

 # Requirements Engineering and Incremental Development Planning Agent
@@ -483,4 +484,19 @@ The agent directly addresses the root causes:

 ---

-*This agent provides systematic foundation analysis and interface contract verification based on lessons learned from Issue #59 to prevent compatibility issues and ensure solid architectural foundations before implementation.*
+## Session Start
+
+1. Check for `.kaizen/agents/requirements-engineering/memory.md` in the project root.
+2. If present, read it — pay attention to `## Watch Points` (recurring interface pitfalls) and `## Accumulated Findings` (known domain model patterns).
+3. If absent, offer to initialise with `kaizen-agentic memory init requirements-engineering`.
+
+## Session Close
+
+1. Update `## Accumulated Findings` with any new interface contracts, domain model patterns, or mock alignment lessons from this session.
+2. Update `## Watch Points` with any newly discovered incompatibility risks.
+3. Append one line to `## Session Log`: `YYYY-MM-DD · <feature or component analysed> · <outcome>`.
+4. Bump `last_updated` to today and increment `session_count`.
+
+---
+
+*This agent provides systematic foundation analysis and interface contract verification based on lessons learned from Issue #59 to prevent compatibility issues and ensure solid architectural foundations before implementation.*
--- a/src/kaizen_agentic/data/agents/agent-setupRepository.md
+++ b/src/kaizen_agentic/data/agents/agent-setupRepository.md
@@ -1,6 +1,7 @@
 ---
-name: setup-repository
+name: setupRepository
 description: Specialized assistant for setting up new Python repositories following PythonVibes best practices
+category: infrastructure
 ---

 ## Instructions
@@ -411,4 +412,4 @@ When setting up or checking repositories, always verify that:
 - Standards compliance is treated as a required test, not optional check
 - Missing .gitignore or other essential files will be caught automatically

-Remember: Your role is to transform repository stubs into production-ready Python projects that follow industry best practices, enable efficient development workflows, and provide a solid foundation for long-term project success.
+Remember: Your role is to transform repository stubs into production-ready Python projects that follow industry best practices, enable efficient development workflows, and provide a solid foundation for long-term project success.
--- a/src/kaizen_agentic/data/agents/agent-tdd-workflow.md
+++ b/src/kaizen_agentic/data/agents/agent-tdd-workflow.md
@@ -143,7 +143,7 @@ You understand the workspace structure (default: `.tddai_workspace/`, configurab
 - `DIRTY` - Workspace directory exists but no current issue file

 ### Test Development Best Practices
-**Test Naming Convention:** 
+**Test Naming Convention:**
 - `test_{capability}_issue_{NUM}_{scenario}.py`

 **Required Test Structure:**
--- a/src/kaizen_agentic/data/agents/agent-test-maintenance.md
+++ b/src/kaizen_agentic/data/agents/agent-test-maintenance.md
@@ -1,8 +1,7 @@
 ---
 name: test-maintenance
-category: development-process
-description: Specialized agent for analyzing and fixing failing tests in projects
-dependencies: []
+description: Specialized agent for analyzing and fixing failing tests in the project
+category: testing
 ---

 # Test-Fixing Agent
@@ -142,4 +141,4 @@ ACTION: Change import path, verify test logic still valid
 - **Communicate trade-offs** when removing functionality
 - **Maintain backward compatibility** where feasible

-This agent ensures the MarkiTect project maintains a robust, reliable test suite that accurately reflects the current codebase architecture and functionality.
+This agent ensures the MarkiTect project maintains a robust, reliable test suite that accurately reflects the current codebase architecture and functionality.
--- a/src/kaizen_agentic/data/agents/agent-testing-efficiency.md
+++ b/src/kaizen_agentic/data/agents/agent-testing-efficiency.md
@@ -1,7 +1,8 @@
 ---
-name: testing-efficiency-optimizer
+name: testing-efficiency
 description: Specialized agent designed to optimize TDD8 workflow test execution, resolve pytest reliability issues, and enhance overall testing efficiency for red-green iterations. Focuses on smart test selection, parallel execution, and agent integration patterns.
 model: inherit
+category: testing
 ---

 # Testing Efficiency Optimizer Agent
@@ -290,4 +291,4 @@ markers =

 ---

-*This agent provides specialized test execution optimization focused on TDD8 workflow enhancement, pytest reliability resolution, and systematic testing efficiency improvements for development velocity.*
+*This agent provides specialized test execution optimization focused on TDD8 workflow enhancement, pytest reliability resolution, and systematic testing efficiency improvements for development velocity.*
--- a/src/kaizen_agentic/data/agents/agent-tooling-optimization.md
+++ b/src/kaizen_agentic/data/agents/agent-tooling-optimization.md
@@ -1,8 +1,7 @@
 ---
 name: tooling-optimization
-category: infrastructure
 description: Meta-agent that analyzes and optimizes repository tooling usage to improve development efficiency
-dependencies: []
+category: infrastructure
 ---

 # Tooling Optimizer Agent
@@ -197,4 +196,4 @@ RECOMMENDATION: Suggest primary tools and deprecation plan for others
 IMPLEMENTATION: Provide migration guide and updated documentation
 ```

-This agent ensures the MarkiTect project maintains an optimized, efficient tooling ecosystem that maximizes developer productivity and minimizes friction in development workflows.
+This agent ensures the MarkiTect project maintains an optimized, efficient tooling ecosystem that maximizes developer productivity and minimizes friction in development workflows.
--- a/src/kaizen_agentic/data/agents/agent-wisdom-encouragement.md
+++ b/src/kaizen_agentic/data/agents/agent-wisdom-encouragement.md
@@ -1,8 +1,9 @@
 ---
 name: wisdom-encouragement
-category: project-management
-description: Provides encouraging wisdom and guidance for developers facing complex implementation challenges
-dependencies: []
+description: "Provides encouraging wisdom and guidance for complex implementation tasks and challenging technical work"
+model: haiku
+color: cyan
+category: documentation
 ---

 You are the Fortune Wisdom Guide, a sage advisor who specializes in providing encouraging, insightful fortune cookie-style wisdom specifically tailored to developers and implementers facing technical challenges. Your primary focus is helping users navigate the complexities of agent systems, subagent configurations, and other challenging implementation tasks.
--- a/tests/test_packaged_agents_parity.py
+++ b/tests/test_packaged_agents_parity.py
@@ -0,0 +1,29 @@
+"""Verify packaged agent data matches canonical agents/ source."""
+
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+AGENTS_SRC = ROOT / "agents"
+AGENTS_PKG = ROOT / "src" / "kaizen_agentic" / "data" / "agents"
+
+
+def _agent_files(directory: Path) -> dict[str, Path]:
+    return {p.name: p for p in sorted(directory.glob("agent-*.md"))}
+
+
+def test_packaged_agents_match_source():
+    """Wheel data/agents must mirror agents/ (names and content)."""
+    src = _agent_files(AGENTS_SRC)
+    pkg = _agent_files(AGENTS_PKG)
+
+    assert src, "agents/ must contain agent-*.md files"
+    assert set(src) == set(pkg), (
+        f"agent file set mismatch\n"
+        f"  only in agents/: {sorted(set(src) - set(pkg))}\n"
+        f"  only in data/agents/: {sorted(set(pkg) - set(src))}"
+    )
+
+    drift = [name for name in src if src[name].read_text() != pkg[name].read_text()]
+    assert not drift, f"content drift in packaged copies: {drift}"
--- a/workplans/kaizen-agentic-WP-0005-adoption-parity.md
+++ b/workplans/kaizen-agentic-WP-0005-adoption-parity.md
@@ -0,0 +1,188 @@
+---
+id: KAIZEN-WP-0005
+type: workplan
+title: "Adoption Polish and Fleet Parity (v1.2.0)"
+domain: custodian
+repo: kaizen-agentic
+status: active
+owner: kaizen-agentic
+topic_slug: custodian
+state_hub_workstream_id: 88c7b3e6-be98-480c-b47b-936e74a1a31b
+created: "2026-06-16"
+updated: "2026-06-16"
+---
+
+# KAIZEN-WP-0005 — Adoption Polish and Fleet Parity
+
+**Status:** active
+**Owner:** kaizen-agentic
+**Repo:** kaizen-agentic
+**Target version:** 1.2.0
+**Depends on:** WP-0001 (v1.1.0 ship), WP-0004 (ecosystem integration docs)
+
+## Goal
+
+Close adoption gaps after the v1.1.0 release: verify the Gitea publish pipeline,
+align all install documentation with the Coulomb registry, enforce packaged-agent
+parity with `agents/`, and harden CI so v1.2.0 ships with confidence.
+
+WP-0001 through WP-0004 delivered features; WP-0005 makes them **discoverable,
+installable, and maintainable** for ecosystem consumers.
+
+---
+
+## Part 1 — Publish Pipeline Verification
+
+Confirm tag-triggered publication works end-to-end before the v1.2.0 cut.
+
+### Tasks
+
+- [x] T01 — Configure `PACKAGE_USER` and `PACKAGE_TOKEN` secrets in Gitea (Gitea rejects `GITEA_*` secret names)
+- [ ] T02 — Smoke-test `.gitea/workflows/publish-python-package.yml` via `workflow_dispatch`
+- [x] T03 — Add pre-tag release checklist to `docs/PACKAGE_RELEASE.md` (secrets, `make package-check`, tag format)
+
+### Definition of done
+
+- Publish workflow succeeds without manual `twine upload`
+- `docs/PACKAGE_RELEASE.md` documents the full operator path
+
+---
+
+## Part 2 — Install Documentation Sync
+
+Several docs still show bare `pip install kaizen-agentic` (pre-Gitea registry).
+
+### Tasks
+
+- [x] T04 — Update `docs/HELLO_WORLD_TUTORIAL.md` install sections (Gitea extra index + pipx)
+- [x] T05 — Update `docs/CLI_CHEAT_SHEET.md` install sections
+- [x] T06 — Update `docs/AGENT_DISTRIBUTION.md` install and distribution sections
+- [x] T07 — Update Makefile `agents-*` fallback messages to point at dev install or `PACKAGE_RELEASE.md`
+- [x] T08 — Cross-link `CONTRIBUTING.md` post-pull reinstall with `docs/PACKAGE_RELEASE.md`
+
+### Definition of done
+
+- No consumer-facing doc implies public pypi.org is the primary install path
+- All install examples use env-var credentials (no committed tokens)
+
+---
+
+## Part 3 — Packaged Fleet Parity
+
+Ensure `pip install` ships the same agent fleet as `agents/`.
+
+### Tasks
+
+- [x] T09 — Add `make agents-sync-package` (copy `agents/agent-*.md` → `data/agents/`) with dry-run mode
+- [x] T10 — Add pytest or `release-check` step verifying `agents/` and `data/agents/` file sets match
+- [x] T11 — Refresh `SCOPE.md` notes and agent-count references (currently stale at 16 vs 20)
+
+### Definition of done
+
+- `make release-check` fails when packaged agents drift from source
+- Wheel contents match canonical `agents/` directory
+
+---
+
+## Part 4 — Release Hygiene and CI
+
+Prepare v1.2.0 versioning and strengthen automated gates.
+
+### Tasks
+
+- [x] T12 — Refresh `TODO.md`: archive 1.1.0 items, point `[Unreleased]` at this workplan
+- [x] T13 — Open `CHANGELOG.md` `[Unreleased]` section for v1.2.0 tracking
+- [x] T14 — Extend `.gitea/workflows/ci.yml` with flake8 (`release-check` lint subset on `src/`)
+
+### Definition of done
+
+- `TODO.md` reflects current vibe-coding state only
+- CI catches lint regressions before merge
+
+---
+
+## Part 5 — Ecosystem Handoff (coordination)
+
+Cross-repo follow-through from WP-0004; no foreign code in this repo.
+
+### Tasks
+
+- [x] T15 — Document activity-core ActivityDefinition registration steps in `docs/INTEGRATION_PATTERNS.md` (handoff checklist for activity-core owners)
+- [x] T16 — Verify bidirectional Helix correlation doc link with agentic-resources (reciprocal link added in `DESIGN-session-memory.md` §11)
+
+### Definition of done
+
+- Operators know how to activate the three ActivityDefinitions committed under `docs/integrations/activity-definitions/`
+- Helix correlation is linked from both repos
+
+---
+
+## Sequencing
+
+```
+Part 1 (T01–T03)  ──→  can run in parallel with Part 2
+        │
+Part 2 (T04–T08)  ──→  Part 4 (T12–T13) doc hygiene
+        │
+Part 3 (T09–T11)  ──→  gates v1.2.0 tag
+        │
+Part 4 (T14)      ──→  before v1.2.0 merge freeze
+        │
+Part 5 (T15–T16)  ──→  non-blocking; parallel with Parts 2–4
+```
+
+Estimated effort: 2–4 sessions.
+
+---
+
+## Out of Scope
+
+- Public pypi.org publication (optional; Gitea registry remains primary)
+- Interactive agent selection wizard (defer to WP-0006)
+- Full `KaizenAgentTemplate.md` schema enforcement in `validate` (defer to WP-0006)
+- Automated documentation generation from agent metadata
+- Owning activity-core, agentic-resources, or artifact-store code
+
+---
+
+## Success Criteria
+
+1. Tag `v1.2.0` triggers Gitea PyPI publish without manual intervention.
+2. A new consumer can install from docs alone (no tribal knowledge about extra index).
+3. Packaged wheel agent fleet cannot drift silently from `agents/`.
+4. WP-0004 ecosystem artifacts have clear operator handoff paths.
+
+---
+
+## State Hub Task IDs
+
+| Code | UUID |
+|------|------|
+| T01 | 1fb6b04e-0854-4cc9-83c7-5abf85fe5bff |
+| T02 | bdb9e463-bdfb-405c-afc4-e93a7d58a18b |
+| T03 | 6a2132e7-8b3f-4960-a5e8-85bad81e8b13 |
+| T04 | 553cba3a-dafa-483a-9200-70ac3f5eb2d7 |
+| T05 | 7e6663a5-fedf-4b1c-acd9-6df6b43d8a12 |
+| T06 | fe553788-357f-45c4-8400-f764f68c1cde |
+| T07 | b131ff67-fe21-4d95-904b-6a0b916c5502 |
+| T08 | 07dd4d25-250c-455c-8363-49269d2ee59f |
+| T09 | 7437cedd-5f7e-4c4d-9142-4f67470c9e52 |
+| T10 | ddbe2114-7a47-48fd-a145-b22dca2b581a |
+| T11 | 5417524f-03c0-40ed-a48b-a7906e6daf8f |
+| T12 | 5cfad56c-2664-4b2d-b5f9-4792c958c9a2 |
+| T13 | fbca9be4-3d2b-4989-baaf-97e6926bdc66 |
+| T14 | a6966cfa-ca59-4087-8989-2870dc69b13f |
+| T15 | fbf3f1a8-4818-473e-ae0d-cd80118e5319 |
+| T16 | 37679ce7-dcb6-42a4-820d-cf8b32c2a248 |
+
+**Hub workstream:** `kaizen-wp-0005-adoption-parity` (`88c7b3e6-be98-480c-b47b-936e74a1a31b`)
+
+---
+
+## Notes
+
+- Deferred from TODO.md [1.1.0]: agent selection wizard, template schema validation,
+  doc generation automation → candidate **WP-0006** (v1.3.0)
+- `make agents-update` updates project-installed agents via CLI; it does **not**
+  sync `agents/` → `data/agents/` — T09 addresses that gap explicitly
+- Part 1 T01 requires Gitea UI access (human step); automation cannot set secrets
Author	SHA1	Message	Date
tegwick	9d2bab9a38	fix: use build venv in Gitea publish workflow (PEP 668) Some checks failed ci / test (push) Failing after 37s Details Haskelseed runner blocks system-wide pip installs. Create an isolated .build-venv for build/twine and document workflow_dispatch API path.	2026-06-16 07:15:57 +02:00
tegwick	5ce3d0766e	docs: mark Helix reciprocal link verified (WP-0005 T16) Update correlation contract status and close T16 in the adoption-parity workplan after agentic-resources DESIGN-session-memory.md §11 landed.	2026-06-16 07:13:13 +02:00
tegwick	e0e02e261d	fix: bootstrap pip on haskelseed runner in Gitea Actions Some checks failed ci / test (push) Failing after 40s Details	2026-06-16 03:27:41 +02:00
tegwick	4daf8635d1	fix: haskelseed-native Gitea Actions without GitHub marketplace Some checks failed ci / test (push) Failing after 6s Details Replace actions/checkout and setup-python with internal git clone and system python3. Drops CI matrix to a single job on the self-hosted runner.	2026-06-16 03:25:41 +02:00
tegwick	2a03eed012	fix: Gitea Actions use haskelseed runner and PACKAGE_* secrets Some checks failed ci / test (3.12) (push) Has been cancelled Details ci / test (3.10) (push) Has been cancelled Details ubuntu-latest never matched the self-hosted runner; Gitea also rejects GITEA_-prefixed secret names. Wire publish workflow to PACKAGE_USER/TOKEN.	2026-06-16 03:13:01 +02:00
tegwick	c004c3d4d7	feat: WP-0005 adoption polish — doc sync, fleet parity, CI lint Some checks failed ci / test (3.10) (push) Has been cancelled Details ci / test (3.12) (push) Has been cancelled Details - Add make agents-sync-package and release-check parity gate - Add tests/test_packaged_agents_parity.py; sync packaged agents with agents/ - Update install docs (HELLO_WORLD, CLI_CHEAT_SHEET, AGENT_DISTRIBUTION) - Expand PACKAGE_RELEASE.md secrets setup and pre-tag checklist - Add flake8 to Gitea CI; CHANGELOG Unreleased for v1.2.0 - Expand INTEGRATION_PATTERNS activity-core handoff checklist	2026-06-16 02:26:13 +02:00
tegwick	4a7f5b2b7d	plan: add WP-0005 adoption polish and fleet parity (v1.2.0) Some checks failed ci / test (3.12) (push) Has been cancelled Details ci / test (3.10) (push) Has been cancelled Details Draft workplan with 16 tasks across publish verification, install doc sync, packaged agent parity, CI hardening, and ecosystem handoff. Refresh TODO.md and SCOPE.md; register State Hub workstream.	2026-06-16 02:21:36 +02:00
tegwick	d7a8357dbf	docs: refresh SCOPE.md for v1.1.0 and completed workplans Some checks failed ci / test (3.12) (push) Has been cancelled Details ci / test (3.10) (push) Has been cancelled Details Move Gitea PyPI to in-scope, mark WP-0001–0004 done, and note WP-0005 as the next planning target.	2026-06-16 02:19:48 +02:00
tegwick	c9a3a77fdf	docs: Gitea PyPI install paths and publish automation Some checks failed ci / test (3.10) (push) Has been cancelled Details ci / test (3.12) (push) Has been cancelled Details Add make package-check/publish-gitea, tag-triggered Gitea Actions workflow, PACKAGE_RELEASE.md, and update README/GETTING_STARTED install instructions for the Coulomb registry (v1.1.0+).	2026-06-16 02:17:30 +02:00