Skip to content

Commit 1165969

Browse files
oskarhaneoskarhane
committed
Update AGENTS docs
1 parent 047dad0 commit 1165969

File tree

6 files changed

+92
-48
lines changed

6 files changed

+92
-48
lines changed

‎.agents/architecture.md‎

Lines changed: 29 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,34 @@
11
# Architecture
22

3-
ARCHITECTURE PATTERN: CLI orchestration with subprocess delegation and a 3‑phase implement/review/finalize loop.
4-
DIRECTORY STRUCTURE: Flat `src/` of single‑purpose modules; `.plans/` for PRD/tasks/progress; `.agents-docs/` for generated docs; tests co‑located in `src/`.
5-
DESIGN PATTERNS: Command-style CLI (Commander), client abstraction (AgentClient), strategy via agent type, prompt builder/templates, atomic file ops for writes/moves.
6-
DATABASE: None; state persisted as YAML/Markdown in `.plans/`.
7-
API DESIGN: Not applicable; CLI commands drive subprocess agents and file-based workflows.
8-
9-
- Code organization: TypeScript modules for config, agent spawning, prompts, PRD/task generation, status, pruning, logging, errors (`src/*.ts`).
10-
- Config management: `.plans/hone.config.yml` with defaults + validation + phase overrides (`src/config.ts`).
11-
- Dependency injection: None; config passed explicitly; logger uses module-level verbosity flag.
12-
- Error handling: Centralized `HoneError`, formatted exits, classification + retry/backoff for network (`src/errors.ts`, `src/agent-client.ts`).
13-
- Logging/monitoring: Verbose toggle + stdout/stderr passthrough; no metrics/tracing (`src/logger.ts`).
14-
- Security patterns: Path traversal checks + permission validation for archive ops; model format validation (`src/prune.ts`, `src/config.ts`).
15-
- Performance considerations: Subprocess streaming, timeouts, bounded retries; mostly small file I/O.
16-
- Middleware/interceptors: None; direct module calls and CLI orchestration.
17-
- API endpoints: None; interactions via CLI and agent subprocesses.
3+
ARCHITECTURE PATTERN: CLI orchestration with subprocess delegation and 3-phase implement/review/finalize loop
4+
5+
DIRECTORY STRUCTURE:
6+
- Flat `src/` with single-purpose TypeScript modules (17 modules + 17 test files co-located)
7+
- `.plans/` for PRD files, task YAML, and config (`hone.config.yml`)
8+
- `.agents/` for generated documentation detail files
9+
- No nested folder hierarchy; one file per concern
10+
11+
DESIGN PATTERNS:
12+
- **Command Pattern**: Commander.js CLI with discrete commands (`init`, `prd`, `run`, `status`, `prune`)
13+
- **Client Abstraction**: `AgentClient` mirrors Anthropic SDK API, wraps subprocess spawning
14+
- **Strategy Pattern**: Agent type (`opencode`/`claude`) determines subprocess command and model arg format
15+
- **Template/Builder**: `constructPrompt()` builds phase-specific prompts for implement/review/finalize
16+
- **Atomic Operations**: Temp file + rename for safe writes/moves in prune operations
17+
18+
DATABASE: None - state persisted as YAML (tasks, config) and Markdown (PRDs) in `.plans/`
19+
20+
API DESIGN: Not applicable - pure CLI tool; interactions via:
21+
- Subprocess spawning of `opencode` or `claude` agents
22+
- File-based workflows (read/write YAML and Markdown)
23+
- Signal handling (SIGINT/SIGTERM) for graceful subprocess termination
24+
25+
Key architectural decisions:
26+
1. **Subprocess delegation**: Core work delegated to AI agent CLIs, hone orchestrates
27+
2. **Phase-based execution**: 3-phase loop (implement→review→finalize) per iteration
28+
3. **File-based state**: No database; `.plans/` directory is source of truth
29+
4. **Model flexibility**: Phase-specific model overrides via config
30+
5. **Error classification**: Structured error parsing with retry logic for network errors only
31+
6. **Atomic file ops**: Safe file moves using temp file patterns
1832

1933
---
2034

‎.agents/build.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
11
# Build System
22

33
BUILD SYSTEMS: [Bun (bun build/compile + bun test), npm scripts via package.json, GitHub Actions workflows]
4-
BUILD COMMANDS: [bun run build, bun run build:linux, bun run build:macos, bun run tsc --noEmit]
4+
5+
BUILD COMMANDS: [bun test, bun run build, bun run build:linux, bun run build:macos, bun run tsc --noEmit]
6+
57
LINT COMMANDS: [bun run lint:yaml, bun run check:yaml]
8+
69
FORMAT COMMANDS: [bun run format, bun run format:yaml, prettier --write "**/*.ts", prettier --write "**/*.yml" "**/*.yaml"]
7-
BUNDLING: [Bun bundler via bun build --compile --minify --sourcemap]
10+
11+
BUNDLING: [Bun native compiler (bun build --compile) - produces standalone binaries for linux-x64 and darwin-arm64]
812

913
---
1014

‎.agents/deployment.md‎

Lines changed: 31 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,36 @@
11
# Deployment
22

3-
DEPLOYMENT STRATEGY: GitHub Actions–driven release workflow producing Bun-compiled binaries + manual npm publish.
4-
CONTAINERIZATION: None detected (no Dockerfile/docker-compose).
5-
CI/CD: GitHub Actions for CI validation, release (major/minor), and manual npm publish via OIDC trusted publishing.
6-
HOSTING: NPM registry for package distribution; GitHub Releases for platform binaries.
7-
ENVIRONMENT MANAGEMENT: CI uses workflow env vars; no repo .env patterns or secrets config beyond GitHub/NPM OIDC.
8-
9-
- Container orchestration: none detected (no K8s/Swarm/Compose).
10-
- Cloud platforms: no AWS/GCP/Azure/Vercel/Netlify/Railway config files found.
11-
- Infrastructure as Code: none detected (no Terraform/CloudFormation/Pulumi).
12-
- Serverless/static: not indicated; CLI binary + npm package focus.
13-
- Database/migrations: none detected (no SQL/migration tooling).
14-
- Monitoring/logging: none detected.
15-
16-
Key evidence
17-
- CI workflow: `.github/workflows/ci.yml`
18-
- Release workflows: `.github/workflows/release-major.yml`, `.github/workflows/release-minor.yml`
19-
- NPM publish: `.github/workflows/publish-npm-manual.yml`
20-
- Build scripts: `package.json` (Bun compile targets Linux/macOS)
3+
DEPLOYMENT STRATEGY: GitHub Actions–driven release workflow producing Bun-compiled binaries + manual npm publish
4+
CONTAINERIZATION: None - CLI tool distributed as standalone binaries
5+
CI/CD: GitHub Actions with 4 workflows (CI validation, release-minor, release-major, npm publish)
6+
HOSTING: Local execution only - distributed via GitHub Releases (binaries) and npm registry (package)
7+
ENVIRONMENT MANAGEMENT: Minimal - CI variables only (`CI=true`, Bun cache dir); no .env files or secrets beyond OIDC
8+
9+
## Pipeline Details
10+
11+
| Workflow | Trigger | Purpose |
12+
|----------|---------|---------|
13+
| `ci.yml` | Push/PR to master | Type check → Tests → Build validation |
14+
| `release-minor.yml` | Manual + CONFIRM | Bump minor, build binaries, create GitHub Release |
15+
| `release-major.yml` | Manual + CONFIRM | Bump major, build binaries, create GitHub Release |
16+
| `publish-npm-manual.yml` | Manual + CONFIRM | Publish to npm via OIDC trusted publishing |
17+
18+
## Build Artifacts
19+
20+
- `hone-linux` - Standalone Bun binary (linux-x64)
21+
- `hone-macos` - Standalone Bun binary (darwin-arm64)
22+
- `hone-ai` npm package for `bunx`/`npx` execution
23+
24+
## Security
25+
26+
- OIDC trusted publishing (no NPM_TOKEN stored)
27+
- Confirmation gates on all release workflows
28+
- `--frozen-lockfile` for dependency integrity
29+
- Remote sync before commits to prevent conflicts
30+
31+
## Not Present
32+
33+
Containerization, cloud providers, IaC, databases, serverless, monitoring - appropriate for local CLI tool distribution model.
2134

2235
---
2336

‎.agents/languages.md‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,13 @@
11
# Project Overview
22

33
PRIMARY LANGUAGES: [TypeScript]
4-
USAGE CONTEXT: [TypeScript for CLI logic, agents orchestration, and test suites under `src/`; no other language ecosystems detected (no Python/Go/Rust/Java configs).]
4+
USAGE CONTEXT: TypeScript is the sole programming language used in this project. It serves as:
5+
- **CLI Application**: Main entry point (`src/index.ts`) using Commander.js for command-line interface
6+
- **Core Business Logic**: Agent orchestration, PRD generation, task generation, and config management
7+
- **Testing**: All test files use Bun's test runner with `.test.ts` and `.integration.test.ts` patterns
8+
- **Build Target**: Compiled to native binaries via Bun for Linux and macOS platforms
9+
10+
No JavaScript source files exist—this is a pure TypeScript codebase running on the Bun runtime.
511

612
---
713

‎.agents/testing.md‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,19 @@
11
# Testing Framework
22

33
TESTING FRAMEWORKS: [Bun test runner (bun:test)]
4-
TEST COMMANDS: [bun test]
5-
TEST ORGANIZATION: [TypeScript tests colocated in src/ with *.test.ts and *.integration.test.ts naming; integration tests use *.integration.test.ts; no dedicated test/ or __tests__ directories]
6-
E2E TESTING: [none detected]
4+
TEST COMMANDS: [`bun test` - runs all tests, `bun run tsc --noEmit` - type checking]
5+
TEST ORGANIZATION:
6+
- Test files colocated with source files in `src/` directory
7+
- Naming convention: `*.test.ts` for unit tests, `*.integration.test.ts` for integration tests
8+
- 18 test files total (mix of unit and integration tests)
9+
- Tests use `describe`/`test`/`expect` from `bun:test`
10+
- Integration tests use CLI spawning via `spawnSync('bun', [CLI_PATH, ...args])`
11+
- Setup/teardown via `beforeEach`/`afterEach`/`beforeAll`/`afterAll` hooks
12+
- Test isolation via temp directories (`test-workspace`, `test-cli-integration`)
13+
- Mock patterns: `mock.module()` for mocking dependencies, env var manipulation for test mode
14+
15+
E2E TESTING: Integration tests spawn actual CLI commands via `spawnSync` against temp directories, providing end-to-end validation of CLI behavior without external network dependencies
716

817
---
918

10-
_This file is part of the AGENTS.md documentation system._
19+
*This file is part of the AGENTS.md documentation system.*

‎AGENTS.md‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
11
<!-- BEGIN GENERATED: AGENTS-MD -->
2-
32
# AGENTS.md
43

54
Learnings and patterns for future agents working on this project.
65

76
## Feedback Instructions
87

9-
TEST COMMANDS: [bun test]
10-
BUILD COMMANDS: [bun run build, bun run build:linux, bun run build:macos, bun run tsc --noEmit]
8+
TEST COMMANDS: [`bun test` - runs all tests, `bun run tsc --noEmit` - type checking]
9+
BUILD COMMANDS: [bun test, bun run build, bun run build:linux, bun run build:macos, bun run tsc --noEmit]
1110
LINT COMMANDS: [bun run lint:yaml, bun run check:yaml]
1211
FORMAT COMMANDS: [bun run format, bun run format:yaml, prettier --write "**/*.ts", prettier --write "**/*.yml" "**/*.yaml"]
1312

@@ -31,21 +30,20 @@ See [@.agents/testing.md](.agents/testing.md) for detailed information.
3130

3231
## Architecture
3332

34-
ARCHITECTURE PATTERN: CLI orchestration with subprocess delegation and a 3‑phase implement/review/finalize loop.
33+
ARCHITECTURE PATTERN: CLI orchestration with subprocess delegation and 3-phase implement/review/finalize loop
3534

3635
See [@.agents/architecture.md](.agents/architecture.md) for detailed information.
3736

3837
## Deployment
3938

40-
DEPLOYMENT STRATEGY: GitHub Actions–driven release workflow producing Bun-compiled binaries + manual npm publish.
39+
DEPLOYMENT STRATEGY: GitHub Actions–driven release workflow producing Bun-compiled binaries + manual npm publish
4140

4241
See [@.agents/deployment.md](.agents/deployment.md) for detailed information.
4342

4443
---
4544

46-
_This AGENTS.md was generated using agent-based project discovery._
47-
_Detailed information is available in the .agents/ directory._
48-
45+
*This AGENTS.md was generated using agent-based project discovery.*
46+
*Detailed information is available in the .agents/ directory.*
4947
<!-- END GENERATED: AGENTS-MD -->
5048

5149
<!-- PRESERVED CONTENT FROM PREVIOUS VERSION -->

0 commit comments

Comments
 (0)