doc: reafirmed project goals and direction

.rdb/session-log.jsonl

@@ -7,3 +7,11 @@
 {"timestamp": "2026-06-02T15:21:45.848114+00:00", "event_type": "command", "target": "rdb status", "details": {}}
 {"timestamp": "2026-06-02T15:40:37.716111+00:00", "event_type": "command", "target": "rdb guardrails", "details": {}}
 {"timestamp": "2026-06-02T15:42:28.735379+00:00", "event_type": "command", "target": "rdb status", "details": {}}
+{"timestamp": "2026-06-02T15:44:50.746110+00:00", "event_type": "command", "target": "rdb status", "details": {}}
+{"timestamp": "2026-06-02T15:44:50.931122+00:00", "event_type": "command", "target": "rdb next", "details": {}}
+{"timestamp": "2026-06-02T15:58:40.572784+00:00", "event_type": "command", "target": "rdb status", "details": {}}
+{"timestamp": "2026-06-02T15:58:44.609967+00:00", "event_type": "command", "target": "rdb next", "details": {}}
+{"timestamp": "2026-06-02T15:58:49.677959+00:00", "event_type": "command", "target": "rdb prompt", "details": {}}
+{"timestamp": "2026-06-02T16:01:01.182387+00:00", "event_type": "command", "target": "rdb status", "details": {}}
+{"timestamp": "2026-06-02T16:05:14.118862+00:00", "event_type": "command", "target": "rdb complete", "details": {"task_id": "TASK-015"}}
+{"timestamp": "2026-06-02T16:05:53.807097+00:00", "event_type": "command", "target": "rdb status", "details": {}}

AGENT_HANDOFF.md

@@ -6,7 +6,7 @@ TASKS_READY
 
 ## Current Task
 
-TASK-014
+TASK-015
 
 ## Instructions For Agent
 

PROJECT_STATE.md

@@ -4,7 +4,7 @@ Current Stage: BUILDING
 Previous Stage: BOOTSTRAP_READY
 Next Stage: REVIEW_READY
 
-Current Task: TASK-014
+Current Task: TASK-015
 Active Branch: main
 
 Last Updated: 2026-06-02

README.md

@@ -1,8 +1,10 @@
 # rdb-discovery
 
-A small CLI-first tool for repeatable software project discovery and delivery.
+A small CLI-first tool that helps you generate and maintain useful project context files for AI-assisted development.
 
-It creates markdown files that help humans and AI coding agents understand:
+## Purpose
+
+rdb-discovery exists to make it easier for humans and AI coding agents to understand:
 
 - what is being built
 - why it exists
@@ -10,6 +12,20 @@ It creates markdown files that help humans and AI coding agents understand:
 - what task should be done next
 - what stage the project is currently in
 
+The tool creates and manages a set of markdown files — your project's source-of-truth context.
+
+## Core workflow
+
+1. **Ask discovery questions** — `rdb discover` captures answers about the product, architecture, risks, and open questions.
+2. **Capture answers** — Structured responses are stored in `context/discovery-log.md` alongside confidence scores and follow-ups.
+3. **Generate context files** — `rdb init` creates standardised project files (`product-brief.md`, `architecture.md`, `decisions.md`, etc.).
+4. **Support agent implementation** — `rdb prompt` produces ready-to-paste implementation prompts for Claude Code or Cline, and `rdb start` / `rdb complete` manage task lifecycles.
+
+## Support features (not the product)
+
+- **Telemetry** records structured agent activity events in `.rdb/session-log.jsonl`. It enables future analysis but is not the main offering.
+- **Guardrails** detect agent stalls, repeated reads, and inconsistent state to keep projects on track. They support the workflow but are secondary.
+
 ## Install for local development
 
 ```bash
@@ -21,23 +37,24 @@ pip install -e '.[dev]'
 ## Commands
 
 ```bash
-rdb init
+rdb init             # Create standard project structure and context files
-rdb discover
+rdb discover         # Ask 10 core discovery questions, record answers
-rdb status
+rdb guardrails       # Check for agent stalls and state inconsistencies
-rdb next
+rdb prompt           # Generate implementation prompt for the next task
-rdb start TASK-001
+rdb start TASK-001   # Mark a task as in progress
-rdb complete TASK-001
+rdb complete TASK-001# Mark a task as done
-rdb handoff
+rdb status           # Show current stage and active task
+rdb next             # Print the next task to work on
+rdb handoff          # Generate agent handoff notes
 ```
 
 ## Bootstrap workflow
 
 1. Run `rdb init`
 2. Run `rdb discover`
-3. Run `rdb status`
+3. Review `rdb status` and `rdb next`
-4. Run `rdb next`
+4. Give the next prompt to Claude Code or Cline via `rdb prompt`
-5. Give the next task to Claude Code or Cline
+5. Commit after each completed task
-6. Commit after each completed task
 
 ## Project structure
 

RUN_LOG.md

@@ -12,3 +12,4 @@ TASK-002 marked Done — agent prompt generation complete.
 | 2026-06-02T10:02:18 | Task completed | TASK-004 | rdb ask-more implemented and tested |
 | 2026-06-02T12:51:20 | Task completed | TASK-007 | enhanced prompts |
 | 2026-06-02T13:45:00 | Task completed | TASK-012 | telemetry foundation — writer, JSONL storage, event reader, 12 tests passed |
+| 2026-06-02T17:05:41 | Task completed | TASK-015 | updated README.md |

TASKS.md

@@ -230,7 +230,91 @@ Acceptance Criteria:
 Result:
 
 Two new guardrail checks added:
+
 - `check_repeated_commands_telemetry` — uses session-log.jsonl to detect repeated CLI commands (>3x)
 - `check_repeated_reads_telemetry` — uses session-log.jsonl to detect repeated file reads (>3x)
-Both integrate into `run_all_guardrails` alongside existing heuristic checks.
+  Both integrate into `run_all_guardrails` alongside existing heuristic checks.
-When telemetry data is absent, both return `"ok"` with an informative fallback message instead of failing.
+  When telemetry data is absent, both return `"ok"` with an informative fallback message instead of failing.
+
+## TASK-015 — Re-centre project purpose
+
+Status: Done
+
+Goal:
+Clarify that rdb-discovery exists to help generate and maintain useful project context files for AI-assisted development.
+
+Implementation Gap:
+
+The project now has task, prompt, guardrail, and telemetry features, but the core product purpose needs to be made explicit again.
+
+Acceptance Criteria:
+
+- Update README.md with a clear project purpose
+- Explain the core workflow:
+  - ask discovery questions
+  - capture answers
+  - generate context files
+  - support agent implementation
+- Clarify that telemetry and guardrails support the workflow but are not the main product
+- Add/update tests only if required
+
+## TASK-016 — Define standard context file templates
+
+Status: Todo
+
+Goal:
+Define the standard context files that rdb-discovery should help generate.
+
+Implementation Gap:
+
+There is not yet a clear built-in definition of the context files the tool should produce.
+
+Acceptance Criteria:
+
+- Define templates for:
+  - company-context.md
+  - development-context.md
+  - infrastructure-context.md
+  - agent-guidelines.md
+  - project-brief.md
+  - architecture.md
+- Templates include headings and placeholder guidance
+- Keep templates simple markdown
+- Add/update tests
+
+## TASK-017 — Generate context files from discovery answers
+
+Status: Todo
+
+Goal:
+Use captured discovery answers to generate initial context files.
+
+Implementation Gap:
+
+Discovery questions can collect information, but the answers are not yet transformed into structured project context documents.
+
+Acceptance Criteria:
+
+- Add command or function to generate context files from discovery data
+- Create missing context files safely
+- Do not overwrite existing files without explicit behaviour
+- Add/update tests
+
+## TASK-018 — Add context completeness report
+
+Status: Todo
+
+Goal:
+Report which expected context files exist and which sections still need information.
+
+Implementation Gap:
+
+There is no way to see whether a project has enough context for an AI agent to work effectively.
+
+Acceptance Criteria:
+
+- Add a context status/check command
+- Report present context files
+- Report missing context files
+- Report obvious placeholder sections still needing completion
+- Add/update tests