From 61014f5ee9f9ecb7a7c93b08f2b9133919f9333b Mon Sep 17 00:00:00 2001 From: Bagas Purwa Sentika Date: Mon, 15 Jun 2026 23:03:06 +0800 Subject: [PATCH] docs(09): capture phase context --- .../09-tooling-portable-setup/09-CONTEXT.md | 130 ++++++++++++++++++ .../09-DISCUSSION-LOG.md | 45 ++++++ 2 files changed, 175 insertions(+) create mode 100644 .planning/phases/09-tooling-portable-setup/09-CONTEXT.md create mode 100644 .planning/phases/09-tooling-portable-setup/09-DISCUSSION-LOG.md diff --git a/.planning/phases/09-tooling-portable-setup/09-CONTEXT.md b/.planning/phases/09-tooling-portable-setup/09-CONTEXT.md new file mode 100644 index 0000000..079acb0 --- /dev/null +++ b/.planning/phases/09-tooling-portable-setup/09-CONTEXT.md @@ -0,0 +1,130 @@ +# Phase 9: Tooling & Portable Setup - Context + +**Gathered:** 2026-06-14 +**Status:** Ready for planning + + +## Phase Boundary + +Create a custom Docker image with essential platform engineering tools and a portable setup script that can provision a fresh macOS machine with all ngn-agent configuration in a single invocation. + +**In scope:** Custom Dockerfile in project repo, image build tooling, parameterized setup script covering all config, file creation, volume mounts, skills, and cron jobs + +**Out of scope:** Installing Hermes Agent itself (assumes Hermes v0.16+ is installed), cloud-native deployment (macOS-only setup), multi-architecture image builds + + + +## Implementation Decisions + +### Custom Docker Image +- **D-01:** Dockerfile lives in this repo at `ngn-agent/docker/Dockerfile` — extends `nikolaik/python-nodejs:python3.11-nodejs20` +- **D-02:** Pin specific tool versions — Dockerfile should specify exact versions for reproducibility +- **D-03:** Tools to include: + - **aws-cli**: v2 (latest stable) + - **terraform**: latest stable + - **helm**: latest stable + - **kubectl**: latest stable matching cluster version + - **datadog CLI** (`pup`): latest stable +- **D-04:** Build script at `ngn-agent/docker/build.sh` — single command to build the image +- **D-05:** Image tag: `ngn-agent:latest` (local only, no registry push) + +### Portable Setup Script +- **D-06:** Single script at `ngn-agent/setup-ngn-agent.sh` — recreates all configuration on a fresh machine +- **D-07:** Assumes Hermes v0.16+ is already installed and `hermes` CLI is on PATH +- **D-08:** Interactive prompts for all secrets: + - `JIRA_API_TOKEN` (required for Atlassian integrations) + - `JIRA_EMAIL` (required for Atlassian integrations) + - `TELEGRAM_BOT_TOKEN` (required for gateway) + - `OPENROUTER_API_KEY` (if not already set) +- **D-09:** Configurable parameters (supplied via args or prompts): + - SSH key paths (default: `~/.ssh/id_ed25519razer`, `~/.ssh/id_rsa`) + - SSH config path (default: `~/.ssh/config`) + - SSH known_hosts path (default: `~/.ssh/known_hosts`) + - Repo paths (default: `~/Razer/rai-ops`, `~/Razer/rai-deployment`, `~/Razer/rai-devtools`) + - Timezone (default: `Asia/Singapore`) +- **D-10:** What the setup script creates/updates: + - `~/.hermes/config.yaml` — docker_volumes (SSH + repo mounts), shell_init_files, docker_forward_env, cron config + - `~/.hermes/.env` — secrets and DEFAULT_REPOS + - `~/.hermes/hindsight/config.json` — Hindsight config + - `~/.hermes/scripts/session-init.sh` — mount verification script + - `~/.hermes/scripts/archive-stale-sessions.sh` — archive script + - `~/.hermes/skills/ngn-agent/` — all 5 skill directories + - `~/.hermes/archive/sessions/` — archive directory + - Register 3 cron jobs (ngn-daily-report, ngn-weekly-stale-summary, ngn-weekly-archive) + - Update Docker image reference in config.yaml + +### the agent's Discretion +- **Dockerfile tool version selection**: Choose stable versions current at time of implementation +- **Setup script structure**: Interactive prompt flow, output formatting, error handling approach +- **Config file templates**: How to generate config.yaml sections, .env format, etc. + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### Project Repo +- `.planning/REQUIREMENTS.md` §TOOL-01, SETUP-01 — Requirement definitions +- `.planning/ROADMAP.md` §Phase 9 — Phase goal and success criteria + +### Current Configuration (what the setup script must recreate) +- `~/.hermes/config.yaml` — Full config with docker_volumes, shell_init_files, docker_forward_env, cron, memory.provider, telegram +- `~/.hermes/.env` — All env vars (JIRA_API_TOKEN, JIRA_EMAIL, TELEGRAM_BOT_TOKEN, OPENROUTER_API_KEY, DEFAULT_REPOS, HINDSIGHT_LLM_API_KEY) +- `~/.hermes/hindsight/config.json` — Hindsight local_embedded config with all settings +- `~/.hermes/scripts/session-init.sh` — Mount verification script +- `~/.hermes/scripts/archive-stale-sessions.sh` — Session archive script +- `~/.hermes/skills/ngn-agent/` — 5 skill files (aws-diagnostics, jira, confluence, bitbucket, session) +- `.planning/phases/08-cron-reporting/08-01-SUMMARY.md` — Cron job registrations +- `.planning/phases/08-cron-reporting/08-02-SUMMARY.md` — Weekly cron job details + +### Base Image +- `nikolaik/python-nodejs:python3.11-nodejs20` — Current Hermes Docker image + +### Existing Skills (templates for setup script) +- `~/.hermes/skills/ngn-agent/aws-diagnostics/SKILL.md` +- `~/.hermes/skills/ngn-agent/jira/SKILL.md` +- `~/.hermes/skills/ngn-agent/confluence/SKILL.md` +- `~/.hermes/skills/ngn-agent/bitbucket/SKILL.md` +- `~/.hermes/skills/ngn-agent/session/SKILL.md` + + + +## Existing Code Insights + +### Reusable Assets +- **Hermes config.yaml** — Current state is the source of truth for what setup script must recreate +- **Skill files** — 5 existing SKILL.md files that setup script must copy into place +- **Script files** — session-init.sh and archive-stale-sessions.sh that setup script must copy +- **Hindsight config.json** — Current config that setup script must create + +### Integration Points +- `ngn-agent/docker/Dockerfile` — New file (create) +- `ngn-agent/docker/build.sh` — New file (create) +- `ngn-agent/setup-ngn-agent.sh` — New file (create) +- `~/.hermes/config.yaml` — Modified by setup script +- `~/.hermes/.env` — Created by setup script with user-provided secrets + + + +## Specific Ideas + +- The setup script should use `hermes config set` where possible instead of raw YAML editing +- Secrets should be prompted interactively with masked input where the terminal supports it +- The setup script should validate prerequisites (Hermes installed, Docker running, SSH keys exist) before making changes +- The Dockerfile should install tools via apt-get and pip where possible, with version pinning via checksums or apt version strings +- After setup, script should offer to restart the Hermes gateway + + + +## Deferred Ideas + +- Multi-architecture image builds (arm64 + amd64) — defer until needed +- Cloud-native deployment (Docker Compose, Fly.io, etc.) — out of scope +- CI/CD for image builds — out of scope + + +--- + +*Phase: 9-Tooling & Portable Setup* +*Context gathered: 2026-06-14* diff --git a/.planning/phases/09-tooling-portable-setup/09-DISCUSSION-LOG.md b/.planning/phases/09-tooling-portable-setup/09-DISCUSSION-LOG.md new file mode 100644 index 0000000..f0dc2e0 --- /dev/null +++ b/.planning/phases/09-tooling-portable-setup/09-DISCUSSION-LOG.md @@ -0,0 +1,45 @@ +# Phase 9: Tooling & Portable Setup - Discussion Log + +> **Audit trail only.** + +**Date:** 2026-06-14 +**Phase:** 9-Tooling & Portable Setup +**Areas discussed:** Custom Docker image, Setup script approach + +--- + +## Custom Docker Image + +| Option | Description | Selected | +|--------|-------------|----------| +| In this repo | Dockerfile in ngn-agent repo, pin tool versions | ✓ | +| Dedicated repo | Separate repo for image build | | + +**User's choice:** In this repo, pin tool versions +**Notes:** Dockerfile at `ngn-agent/docker/Dockerfile`, build script at `ngn-agent/docker/build.sh`. + +--- + +## Setup Script Approach + +| Option | Description | Selected | +|--------|-------------|----------| +| Full setup + config | All config, secrets prompted, directory creation, volume mounts, skills, cron | ✓ | +| Config only | Just copy config files | | + +**User's choice:** Full setup. Secrets specified during setup with interactive prompts. +**Notes:** Script creates everything. Assumes Hermes installed. Interactive prompts for secrets. + +--- + +## the agent's Discretion + +- Dockerfile tool version selection +- Setup script interactive flow design +- Config file template generation + +## Deferred Ideas + +- Multi-architecture builds +- Cloud-native deployment +- CI/CD for images