diff --git a/README.md b/README.md index 55142332..90ca86f4 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,10 @@ The purpose is simple: create an idea, task, or issue in Linear; ADHD.ai pulls t Production default: run unattended processing with `adhd-ai cron`. Use `adhd-ai run --poll` as a local/dev mode when iterating on workflow behavior. +## Operator Guide + +For non-technical operators, start with [NON_TECHNICAL_GUIDE.md](docs/NON_TECHNICAL_GUIDE.md). + ## Purpose - Use Linear as the job board for engineering ideas, tasks, and issues. diff --git a/docs/NON_TECHNICAL_GUIDE.md b/docs/NON_TECHNICAL_GUIDE.md new file mode 100644 index 00000000..996d34ac --- /dev/null +++ b/docs/NON_TECHNICAL_GUIDE.md @@ -0,0 +1,78 @@ +# ADHD.ai Non-Technical Guide + +This guide explains how to use ADHD.ai as an operator without needing to read the codebase. + +## What ADHD.ai Does + +ADHD.ai takes work tracked in Linear and moves it through an automated engineering workflow: + +1. planning +2. implementation +3. review and testing + +The system keeps Linear and GitHub updated as work advances. + +## Basic Workflow + +1. A person creates or assigns a Linear issue. +2. ADHD.ai picks up eligible issues based on project routing config. +3. A planning agent writes a concrete implementation plan. +4. An implementation agent changes code in the target repository and updates the pull request context. +5. A review/testing agent validates the result. +6. If review/testing fails, ADHD.ai loops back to implementation with structured bug feedback. +7. The issue ends as `done` or `blocked`. + +## How Each Integration Fits + +### Linear + +Linear is the work queue and progress tracker. + +- Issues are the source of truth for what should be done. +- Status and comments are updated as stages change. +- Complex planning outputs can be split into child issues. + +### GitHub + +GitHub is where code changes are reviewed and tracked. + +- ADHD.ai creates or updates branch/PR context during implementation. +- Review/testing feedback is tied back to the same work stream. +- PR history gives an audit trail of what changed. + +### Resend (Optional) + +Resend is used only for optional email notifications. + +- ADHD.ai can send terminal outcome notifications (`done` or `blocked`). +- If Resend is not configured, the core workflow still works. + +### Claude and OpenAI Codex + +ADHD.ai runs agent stages using a configurable backend and model settings. + +- Planning, implementation, and review/testing can use configured models. +- Claude/OpenAI Codex are runtime options, not both required at the same time. +- Behavior depends on your project config and environment values. + +## Operator Setup and First Run + +1. Run `adhd-ai setup` and answer prompts. +2. Run `adhd-ai setup --check` to validate config and required tooling. +3. Run `bun run src/index.ts projects` to confirm project resolution. +4. Start one scoped run: `bun run src/index.ts run --project `. +5. Confirm run state appears under `.piv-loop/projects//runs`. + +More detail: + +- onboarding flow: [new-user-onboarding.md](product-specs/new-user-onboarding.md) +- operations and plan contract: [PLANS.md](PLANS.md) +- reliability behavior: [RELIABILITY.md](RELIABILITY.md) + +## What To Check When Work Is Blocked + +1. Confirm the issue is in the expected Linear status and assigned to the expected project. +2. Check run state and errors under `.piv-loop/projects//`. +3. Verify required credentials exist in environment or local secret storage. +4. Confirm GitHub authentication and repository routing are valid. +5. Re-run with scoped flags (`--project`, `--issue`) to isolate one workflow path. diff --git a/docs/product-specs/index.md b/docs/product-specs/index.md index b5cdbd8d..a9cfa687 100644 --- a/docs/product-specs/index.md +++ b/docs/product-specs/index.md @@ -4,7 +4,8 @@ ADHD.ai turns Linear issues into staged agent execution with planning, implement ## Current Specs -- [new-user-onboarding.md](/Users/roy/Desktop/SourceCode/agentic/show-me-ur-agents/docs/product-specs/new-user-onboarding.md) +- [new-user-onboarding.md](new-user-onboarding.md) +- [NON_TECHNICAL_GUIDE.md](../NON_TECHNICAL_GUIDE.md) ## Product Workflow Summary diff --git a/skills/README.md b/skills/README.md index 2b2502d6..6fa5c744 100644 --- a/skills/README.md +++ b/skills/README.md @@ -9,6 +9,7 @@ This directory is the default skill pack root for ADHD.ai. - `piv-plan/SKILL.md` - `piv-implement/SKILL.md` - `piv-review-test/SKILL.md` +- `adhd-docs/SKILL.md` ## Configure a custom skill root @@ -44,3 +45,7 @@ You can source skills from another repo in three common ways: 3. Copy selected skill folders into this `skills/` directory. For reproducibility, pin submodules or clone to a known commit. + +## Included Documentation Skill + +`adhd-docs/SKILL.md` is for generating and maintaining plain-language, operator-facing documentation that explains workflow behavior and integrations (Linear, GitHub, optional Resend notifications, and Claude/OpenAI Codex runtime options) without exposing secrets. diff --git a/skills/adhd-docs/SKILL.md b/skills/adhd-docs/SKILL.md new file mode 100644 index 00000000..32a2ccf9 --- /dev/null +++ b/skills/adhd-docs/SKILL.md @@ -0,0 +1,37 @@ +--- +name: adhd-docs +description: Documentation skill for producing plain-language ADHD.ai guides for non-technical operators. +--- + +# ADHD.ai Docs Skill + +You are the documentation agent for ADHD.ai. + +## Goals + +1. Explain ADHD.ai in plain language for non-technical operators. +2. Describe how the workflow moves from Linear intake to done/blocked outcomes. +3. Clarify how integrations are used without exposing secrets. +4. Keep documentation short, accurate, and directly usable. + +## Writing Rules + +1. Use concrete terms and short sentences. +2. Avoid internal implementation jargon unless it is required, and define it when used. +3. Separate required setup from optional features. +4. Keep operator actions explicit: what to run, what to check, what success looks like. + +## Integration Coverage + +When relevant, briefly explain: + +1. Linear: issue intake, routing, statuses, and progress visibility. +2. GitHub: branch and PR lifecycle for implementation and review. +3. Resend: optional terminal outcome email notifications. +4. Claude/OpenAI Codex: configurable agent backend and model selection for planning, implementation, and review/testing. + +## Safety Constraints + +1. Do not include API keys, tokens, or secret examples. +2. Do not claim integrations are mandatory when they are optional in config. +3. If behavior depends on configuration, state that dependency clearly.