ngn-agent/.planning/PROJECT.md

ngn-agent

What This Is

ngn-agent is a platform engineering agent powered by Nous Research's Hermes Agent. It manages multi-project infrastructure work through isolated sessions, connects via Telegram gateway, runs commands in Docker containers with limited AWS IAM roles, and persists knowledge across sessions via Hermes' memory system. Designed for platform engineers who manage real infrastructure and need guardrails against accidental mutations.

Core Value

The agent must NEVER mutate real infrastructure beyond what the limited IAM role permits, while being maximally useful for diagnostics, research, and automation.

Requirements

Validated

(None yet — ship to validate)

Active

• AUTH-01: Agent authenticates via AWS Bedrock as primary LLM provider

• AUTH-02: Agent falls back to OpenRouter when Bedrock is unavailable

• AUTH-03: Agent uses limited SSO role via project-local ./.aws/ config

• AUTH-04: Agent runs commands inside Docker containers with host hardening

• AUTH-05: Hermes persistent memory stores infrastructure facts and user preferences

• AUTH-06: Hermes session search allows recalling past infrastructure context

• GATE-01: Telegram gateway allows multi-project session management

• GATE-02: Users interact with the agent via Telegram DMs

• GATE-03: Pairing-based authorization for new users

• GATE-04: Scheduled daily reports and stale session cleanup

• SKIL-01: Self-improving skills system with skills hub integration

• SKIL-02: Infrastructure diagnostic skills (read-only by default)

• SKIL-03: AWS cost/health/resource querying via read-only tools

• SKIL-04: Jira and Confluence integration for reporting

• SKIL-05: Git worktree isolation for parallel branch work

• OPS-01: Minimal dependencies, repeatable setup via single install

• OPS-02: .env file for credential management

• OPS-03: ~/.aws: never mounted; ./.aws with limited role mounted instead

• OPS-04: Dangerous command approval and hardline blocklist active

Out of Scope

• Direct ~/.aws mounting — use scoped ./.aws instead
• Full kubectl exec / terraform apply access without explicit approval gates
• Non-AWS cloud providers (GCP/Azure) — defer to future
• Native mobile app — Telegram gateway is the mobile interface
• Self-hosted model serving — use Bedrock/OpenRouter

Context

• Base tool: Nous Research Hermes Agent (Python/uv, MIT)
• Runtime: macOS (Orbstack for Docker), CLI-only install (no Desktop)
• LLM: AWS Bedrock (primary) via boto3 SSO auth → OpenRouter (fallback)
• Terminal backend: Docker with hardened security (--cap-drop ALL, no-new-privileges)
• Memory: Hermes persistent memory (MEMORY.md + USER.md) + FTS5 session search
• Credentials: ./.aws/ with limited IAM role mounted read-only into Docker; ~/.hermes/.env for OpenRouter key
• AWS auth: SSO role chaining with cached session (~7 day refresh), browser login on expiry
• Project location: /Users/bapung/Razer/ngn-agent

Constraints

• Security: Agent must run inside Docker with limited capabilities
• Credential: Only scoped AWS role — never raw admin access
• Auth: Bedrock uses boto3 chain (SSO); no API key for primary provider
• Provider: OpenRouter key in .env for fallback only
• Git: Worktree-based isolation; pushes only to feature branches
• Gateway: Telegram as primary messaging channel

Key Decisions

Decision	Rationale	Outcome
Hermes Agent over NanoClaw	Superior memory system (auto-learning, session search, 8 external providers)	✓ Good
Bedrock primary + OpenRouter fallback	Zero additional API cost for primary (uses existing AWS SSO); OpenRouter as reliability layer	— Pending
Docker backend	Container isolation is the security boundary; dangerous command checks skipped	— Pending
Project-local ./.aws	Prevents privileged credentials from entering container	— Pending
CLI-only install	Desktop not needed; minimal surface area	— Pending
Git worktree isolation	Prevents branch contamination across sessions	— Pending

Evolution

This document evolves at phase transitions and milestone boundaries.

After each phase transition (via /gsd-transition):

1. Requirements invalidated? → Move to Out of Scope with reason
2. Requirements validated? → Move to Validated with phase reference
3. New requirements emerged? → Add to Active
4. Decisions to log? → Add to Key Decisions
5. "What This Is" still accurate? → Update if drifted

After each milestone (via /gsd-complete-milestone):

1. Full review of all sections
2. Core Value check — still the right priority?
3. Audit Out of Scope — reasons still valid?
4. Update Context with current state

---

Last updated: 2026-06-14 after initialization