Codex/roy 30

AGENTS.md

@@ -1,41 +1,32 @@
-# ADHD.ai Agent Alignment
+# ADHD.ai Agent Entry
 
-This repository supports multi-project orchestration. Keep behavior consistent across projects and avoid coupling workflow logic to one workspace.
+This repository orchestrates multi-project agent workflows. Keep behavior project-agnostic and avoid coupling logic to a single workspace.
 
-## Architecture Guardrails
+## Must-Follow Rules
 
-1. `src/config.ts` is the only place that resolves env vars and config files into project runtime config.
-2. `src/workflow.ts` owns stage transitions and orchestration sequencing.
-3. Integration modules stay isolated:
-   - `src/linear.ts`
-   - `src/github.ts`
-   - `src/codex.ts`
-4. `src/state.ts` owns run-state paths and compatibility fallback.
-5. CLI parsing and command dispatch live in:
-   - `src/args.ts`
-   - `src/index.ts`
-
-## Multi-Project Rules
-
-1. Every run must resolve to one or more `project.id` values.
-2. Persist run state under `.piv-loop/projects/<project-id>/runs`.
-3. Status reads require an explicit project id.
-4. Default invocation without project flags runs the first configured project.
-
-## Coding Rules
-
-1. Do not read env vars outside `src/config.ts`.
-2. Do not construct raw shell command strings in workflow logic; use helper modules.
-3. Keep parsing contracts stable for review output:
+1. Resolve env vars and config only in `src/config.ts`.
+2. Keep stage transitions and sequencing in `src/workflow.ts`.
+3. Keep integrations isolated in `src/linear.ts`, `src/github.ts`, and `src/codex.ts`.
+4. Keep run-state path logic in `src/state.ts`.
+5. Keep CLI parsing and dispatch in `src/args.ts` and `src/index.ts`.
+6. Do not construct raw shell command strings in workflow logic; use helper modules.
+7. Keep review parsing contract stable:
    - `RESULT: PASS|FAIL`
    - `SUMMARY: ...`
    - `BUGS_JSON: [...]`
-4. Add tests for any new CLI flag, config shape, state path, or stage transition.
+8. Add tests for any new CLI flag, config shape, state path, or stage transition.
 
 ## Quality Gates
 
-Run all of these before finalizing changes:
+Run all checks before finalizing changes:
 
 1. `bun run check`
 2. `bun run typecheck`
 3. `bun test`
+
+## Documentation Map
+
+- Architecture details: [ARCHITECTURE.md](/Users/roy/Desktop/SourceCode/agentic/show-me-ur-agents/ARCHITECTURE.md)
+- Execution and operating plans: [docs/PLANS.md](/Users/roy/Desktop/SourceCode/agentic/show-me-ur-agents/docs/PLANS.md)
+- Reliability and run behavior: [docs/RELIABILITY.md](/Users/roy/Desktop/SourceCode/agentic/show-me-ur-agents/docs/RELIABILITY.md)
+- Security and secrets handling: [docs/SECURITY.md](/Users/roy/Desktop/SourceCode/agentic/show-me-ur-agents/docs/SECURITY.md)

ARCHITECTURE.md

@@ -0,0 +1,40 @@
+# Architecture
+
+## System Purpose
+
+ADHD.ai is a multi-project orchestration hub that pulls eligible Linear issues and executes a staged agent loop: planning, implementation, and review/testing.
+
+## Ownership Boundaries
+
+1. `src/config.ts` is the only runtime config resolver for env vars and config files.
+2. `src/workflow.ts` owns stage transitions, retries, and orchestration order.
+3. Integration modules stay isolated:
+   - `src/linear.ts`
+   - `src/github.ts`
+   - `src/codex.ts`
+4. `src/state.ts` owns run-state paths and legacy fallback behavior.
+5. `src/args.ts` and `src/index.ts` own CLI parsing and command dispatch.
+
+## Stage Model
+
+The workflow advances through planning -> implementing -> testing and synchronizes Linear status and comments at each boundary. Review output must preserve the parsing contract:
+
+- `RESULT: PASS|FAIL`
+- `SUMMARY: ...`
+- `BUGS_JSON: [...]`
+
+## Multi-Project Runtime Rules
+
+1. Every run resolves to one or more `project.id` values.
+2. Run state is persisted under `.piv-loop/projects/<project-id>/runs`.
+3. Status reads require an explicit project id.
+4. Default invocation without project flags targets the first configured project.
+5. `--all-projects --issue <KEY>` must resolve to one unique project mapping.
+
+## Integration Flow
+
+1. Linear issues are fetched and routed by project config and optional `linear.projectId`.
+2. Planning prompt is built from issue context and skill input.
+3. Implementation session applies code changes and creates/updates PR context.
+4. Review/testing session emits structured pass/fail output and bug payload.
+5. Failed verification feeds back into implementation until pass or blocked.

docs/DESIGN.md

@@ -0,0 +1,10 @@
+# Design
+
+ADHD.ai design goals:
+
+1. Keep stage behavior legible and deterministic.
+2. Favor narrow ownership boundaries per module.
+3. Keep docs aligned with actual runtime behavior, not aspirational behavior.
+4. Preserve compatibility where explicitly supported (for example legacy config fallback).
+
+See [docs/design-docs/index.md](/Users/roy/Desktop/SourceCode/agentic/show-me-ur-agents/docs/design-docs/index.md) for detailed design writeups.

docs/FRONTEND.md

@@ -0,0 +1,10 @@
+# Frontend
+
+This repository currently has no user-facing frontend application.
+
+Operator surfaces are CLI output, Linear comments, and GitHub PR metadata. If a frontend is introduced, document:
+
+1. user workflows and personas
+2. API boundaries
+3. reliability and auth model
+4. deployment and rollback strategy

docs/PLANS.md

@@ -0,0 +1,25 @@
+# Plans
+
+Execution plans and plan artifacts are tracked under `docs/exec-plans/`.
+
+## Workflow Plan Contract
+
+Planning output should remain concise and implementation-focused, including:
+
+1. scope summary
+2. implementation steps
+3. test plan
+4. known risks
+
+## Operating Commands
+
+1. `bun run src/index.ts run --project default`
+2. `bun run src/index.ts run --all-projects`
+3. `bun run src/index.ts status --project default --issue ENG-123`
+4. `bun run src/index.ts projects`
+
+## Quality Commands
+
+1. `bun run check`
+2. `bun run typecheck`
+3. `bun test`

docs/PRODUCT_SENSE.md

@@ -0,0 +1,17 @@
+# Product Sense
+
+ADHD.ai exists to convert issue-tracker intent into reliable engineering progress across one or many projects.
+
+## Primary User Value
+
+1. Pull eligible Linear work automatically.
+2. Route work to the right project context.
+3. Execute staged agent work: plan -> implement -> verify.
+4. Keep status, labels, comments, and PR context synchronized.
+
+## Product Principles
+
+1. Project routing must be explicit and auditable.
+2. Recovery from partial runs should be safe and predictable.
+3. Structured outputs should be machine-parseable for loop automation.
+4. Human operators should always be able to inspect current stage and outcome.

docs/QUALITY_SCORE.md

@@ -0,0 +1,13 @@
+# Quality Score
+
+Quality in this repository is currently gate-based.
+
+## Required Gates
+
+1. `bun run check`
+2. `bun run typecheck`
+3. `bun test`
+
+## Suggested Tracking
+
+Track quality trends over time in this file once score dimensions are defined (for example test stability, workflow retries, and failure recovery rate).

docs/RELIABILITY.md

@@ -0,0 +1,22 @@
+# Reliability
+
+## Runtime Expectations
+
+1. Each run resolves to one or more `project.id` values.
+2. Project-scoped state is persisted under `.piv-loop/projects/<project-id>/runs`.
+3. Status reads require explicit project id context.
+4. Default non-project invocation runs against the first configured project.
+
+## Polling and Recovery
+
+1. Polling is configured globally (`intervalMs`, `maxCycles`, `exitWhenIdle`, `staleRunTimeoutMs`).
+2. Stale in-progress runs are eligible for requeue after timeout.
+3. `--all-projects --issue` must resolve to one unique project mapping.
+
+## Verification Signal Contract
+
+Review/testing output must preserve:
+
+- `RESULT: PASS|FAIL`
+- `SUMMARY: ...`
+- `BUGS_JSON: [...]`

docs/SECURITY.md

@@ -0,0 +1,18 @@
+# Security
+
+## Secrets and Credentials
+
+1. Treat API keys and tokens as environment-provided secrets.
+2. Do not hardcode credentials in repository files.
+3. Keep environment resolution centralized in `src/config.ts`.
+
+## Command Safety
+
+1. Avoid raw shell command construction in workflow logic.
+2. Use module-level helpers for command execution and argument handling.
+
+## Integration Access
+
+1. Linear access is scoped by configured API key and optional project routing.
+2. GitHub actions should run through authenticated `gh` usage.
+3. Codex execution settings should remain explicit in config and per-project overrides.

docs/design-docs/core-beliefs.md

@@ -0,0 +1,7 @@
+# Core Beliefs
+
+1. Multi-project behavior is a first-class requirement, not an afterthought.
+2. Workflow stages must be explicit, observable, and resumable.
+3. Integration boundaries should stay narrow to reduce coupling and regressions.
+4. Structured review output is critical for automation loops and issue creation.
+5. Safety defaults matter: dry-run support, explicit routing, and clear state ownership.

docs/design-docs/index.md

@@ -0,0 +1,11 @@
+# Design Docs Index
+
+This section tracks design-level thinking for ADHD.ai behavior and operator experience.
+
+## Documents
+
+- [core-beliefs.md](/Users/roy/Desktop/SourceCode/agentic/show-me-ur-agents/docs/design-docs/core-beliefs.md)
+
+## Notes
+
+Add future design docs here as problem-specific writeups (for example polling UX, run recovery UX, or review feedback presentation).

docs/exec-plans/.gitkeep

@@ -0,0 +1 @@
+

docs/exec-plans/active/.gitkeep

@@ -0,0 +1 @@
+

docs/exec-plans/completed/.gitkeep

@@ -0,0 +1 @@
+

docs/exec-plans/tech-debt-tracker.md

@@ -0,0 +1,17 @@
+# Tech Debt Tracker
+
+Use this file to track debt items that cut across projects, stage orchestration, or integration reliability.
+
+## Template
+
+- `id`: short slug
+- `area`: config | workflow | state | linear | github | codex | cli | tests
+- `impact`: low | medium | high
+- `symptom`: concise description
+- `proposed-fix`: concise remediation
+- `owner`: team or role
+- `target`: milestone or date
+
+## Open Items
+
+None yet.

docs/generated/db-schema.md

@@ -0,0 +1,5 @@
+# DB Schema (Generated)
+
+No database schema artifact is currently generated in this repository.
+
+If schema generation is added later, publish the generated output here and document the generation command in [docs/PLANS.md](/Users/roy/Desktop/SourceCode/agentic/show-me-ur-agents/docs/PLANS.md).

docs/product-specs/index.md

@@ -0,0 +1,16 @@
+# Product Specs Index
+
+ADHD.ai turns Linear issues into staged agent execution with planning, implementation, and verification loops.
+
+## Current Specs
+
+- [new-user-onboarding.md](/Users/roy/Desktop/SourceCode/agentic/show-me-ur-agents/docs/product-specs/new-user-onboarding.md)
+
+## Product Workflow Summary
+
+1. Operator creates or assigns work in Linear.
+2. ADHD.ai fetches eligible issues by project routing rules.
+3. Planning agent produces implementation strategy.
+4. Implementation agent updates code and PR context.
+5. Review/testing agent validates and returns structured pass/fail output.
+6. Failures are fed back into implementation until done or blocked.

docs/product-specs/new-user-onboarding.md

@@ -0,0 +1,38 @@
+# New User Onboarding
+
+## Goal
+
+Get a new operator from zero setup to running a scoped project workflow.
+
+## Preconditions
+
+1. Repository is cloned.
+2. `bun` and `gh` are installed.
+3. Linear and GitHub credentials are available.
+
+## Setup
+
+1. Configure required environment variables:
+   - `LINEAR_API_KEY`
+   - `LINEAR_STATUS_ASSIGNED`
+   - `LINEAR_STATUS_PLANNING`
+   - `LINEAR_STATUS_IMPLEMENTING`
+   - `LINEAR_STATUS_PR_CREATED`
+   - `LINEAR_STATUS_REVIEWING`
+   - `LINEAR_STATUS_TESTING`
+   - `LINEAR_STATUS_BLOCKED`
+   - `LINEAR_STATUS_DONE`
+2. Review `adhd-ai.config.ts` and confirm `projects[]` entries, `project.id`, and paths.
+3. Verify GitHub auth with `gh auth status`.
+
+## First Run
+
+1. Run `bun run src/index.ts projects` to verify project resolution.
+2. Run `bun run src/index.ts run --project <PROJECT_ID>` for one scoped project.
+3. Validate run state appears under `.piv-loop/projects/<project-id>/runs`.
+
+## Success Criteria
+
+1. One issue is picked up for the selected project.
+2. Stage transitions reach planning and implementation.
+3. Linear comments reflect workflow progress.

docs/references/design-system-reference-llms.txt

@@ -0,0 +1,2 @@
+Placeholder reference file.
+Add design-system guidance for LLM workflows when available.

docs/references/nixpacks-llms.txt

@@ -0,0 +1,2 @@
+Placeholder reference file.
+Add Nixpacks guidance for LLM workflows when available.

docs/references/uv-llms.txt

@@ -0,0 +1,2 @@
+Placeholder reference file.
+Add uv guidance for LLM workflows when available.