EvoCoder – Introduce /codex/: STATE.md board, tickets, plans, and agents.md

codex/STATE.md

@@ -0,0 +1,17 @@
+# Codex State Board
+
+This table is the single source of truth for active and historical tickets. Keep it alphabetically sorted by ticket ID and update it whenever any metadata changes.
+
+| Ticket ID | Title | Status | Priority | Owner | PRs | Last Updated |
+|-----------|-------|--------|----------|-------|-----|--------------|
+| — | — | — | — | — | — | — |
+
+## Usage Guidelines
+
+- **Status** must be one of `Backlog`, `In-Progress`, `Review`, or `Done`.
+- **Priority** codes follow the scale `P0` (blockers) through `P3` (nice-to-have).
+- **Owner** should be the GitHub handle responsible for delivery.
+- **PRs** should list merged or open pull requests as Markdown links (separate multiple entries with `<br>`).
+- **Last Updated** records the most recent date (`YYYY-MM-DD`) that any field changed.
+
+After a ticket is marked **Done**, leave the row in place for history but do not edit it further. If new work emerges, capture it as a fresh ticket with a unique ID.

codex/agents.md

@@ -0,0 +1,64 @@
+# Codex Workspace Overview
+
+The `/codex` directory centralises planning artefacts so work can be tracked and audited without relying on external tools. Every ticket progresses through a shared lifecycle that keeps the board, ticket logs, and pull requests synchronised.
+
+## Workflow Fundamentals
+
+- **Open a ticket**: Create a new Markdown file under `codex/tickets/` using the ticket template. Assign a unique ID that matches the filename (`ticket-ID.md`) and choose an initial priority (P0–P3).
+- **Register the ticket**: Add a row to `codex/STATE.md` capturing the ticket metadata. The table is the authoritative board and must mirror the ticket front matter.
+- **Deliver incremental work**: Keep updates small, land pull requests frequently, and cross-reference the ticket in PR descriptions.
+- **Maintain the board**: Whenever the status, owner, linked PRs, or priority changes, update both the ticket front matter and the `STATE.md` row.
+- **Close the loop**: Before marking a ticket **Done**, verify the acceptance criteria, ensure linked PRs are merged, and capture the final log entry.
+
+## Directory Layout
+
+- `/codex/STATE.md`: Master board of tickets, tracked as a Markdown table. Every ticket ID listed here must have a matching file in `codex/tickets/`.
+- `/codex/tickets/`: Canonical ticket records with context, plan, acceptance checks, PR links, and chronological log entries.
+- `/codex/plans/`: Time-boxed planning documents (for example, sprint briefs) that roll tickets into broader initiatives and demos.
+
+> Tip: Avoid editing tickets marked **Done**—append follow-up work as a new ticket to keep historical artefacts immutable.
+
+## Ticket Status Lifecycle
+
+Tickets use one of the four Codex statuses:
+
+- **Backlog** – Defined work that is not yet being executed.
+- **In-Progress** – Active engineering work; log meaningful events daily.
+- **Review** – Waiting on pull request review, sign-off, or external validation.
+- **Done** – Ticket verified, acceptance criteria satisfied, no further work expected.
+
+Only move a ticket forward (never backwards) unless there is an explicit reset of scope. When rolling back, add a log entry explaining the decision.
+
+## Board Hygiene Expectations
+
+- Update the `Last Updated` column every time a ticket changes state, owner, or linked PRs.
+- Use GitHub handles for the **Owner** column to line up with PR mentions.
+- Track PR references as Markdown links (e.g. `[PR #123](https://github.com/org/repo/pull/123)`).
+- Leave placeholder rows out of the board—`STATE.md` should only list active or historical tickets.
+
+## Ticket Authoring Standards
+
+- Maintain the YAML front matter in alphabetical key order: `created`, `id`, `owner`, `priority`, `status`, `title`.
+- Use ISO 8601 dates (`YYYY-MM-DD`) for `created` and timestamps in the log.
+- Keep the **Plan** section as a living checklist; strike through or mark completed items with `[x]`.
+- Capture risks, external dependencies, and decisions in log entries so reviewers can audit the timeline.
+
+## Planning Documents
+
+Planning files in `codex/plans/` should:
+
+- Follow the naming convention `YYYYWW-name.md` (calendar week) or `YYYY-QN-name.md` for quarterly plans.
+- Document the planning window, goals, committed tickets, stretch objectives, demo notes, and retro actions.
+- Link back to ticket IDs and keep status snapshots so stakeholders can see progression across the time box.
+
+## Codex Agent Contract
+
+Codex agents working in this repository must:
+
+1. Read `codex/STATE.md` before beginning new work to avoid conflicts.
+2. Log every material action or decision in the ticket's **Log** section with timestamped bullet notes.
+3. Keep ticket files and `STATE.md` in sync for status, priority, ownership, and PR references.
+4. Never modify tickets marked **Done**—open a follow-up ticket instead.
+5. Ensure every merged PR references its ticket ID and that the ticket references the PR.
+
+By keeping the board, tickets, and plans tightly aligned, contributors maintain a single source of truth that scales across teams and long-running initiatives.

codex/plans/README.md

@@ -0,0 +1,40 @@
+# Planning Document Guide
+
+Planning artefacts in this directory provide a lightweight structure for organising tickets into time-boxed initiatives (sprints, OKRs, releases).
+
+## Naming Convention
+
+- Weekly plans: `YYYYWW-name.md` (e.g., `2025W41-sprint.md`)
+- Quarterly plans: `YYYY-QN-name.md` (e.g., `2025-Q1-growth.md`)
+
+## Recommended Outline
+
+```markdown
+# 2025W41 – Acquisition Sprint
+
+**Window:** 2025-10-06 → 2025-10-17  
+**Facilitator:** github-handle  
+**Goals:** Bullet list of top-level objectives.
+
+## Committed Tickets
+
+- TKT-1234 – Short description and owner
+
+## Stretch Tickets
+
+- TKT-2345 – Optional goals if capacity allows
+
+## Milestones
+
+- 2025-10-08 – Mid-sprint review agenda, demo targets, or checkpoints.
+
+## Demo & Review Notes
+
+- Capture outcomes, learnings, and retro action items.
+```
+
+## Best Practices
+
+- Reference ticket IDs consistently so readers can jump to the source ticket record.
+- Note capacity or staffing risks early and keep this file updated after standups or planning meetings.
+- Archive completed plans in place—do not delete them. They serve as historical context for future planning cycles.

codex/tickets/README.md

@@ -0,0 +1,55 @@
+# Codex Ticket Authoring Guide
+
+Each ticket is stored as a Markdown file in this directory with the filename `<ticket-id>.md` (for example, `TKT-1234.md`). The file begins with YAML front matter followed by structured sections that capture context, plan, acceptance, links, and a running log.
+
+## Front Matter Template
+
+```yaml
+---
+created: 2024-01-15
+id: TKT-1234
+owner: octocat
+priority: P1
+status: In-Progress
+title: Upgrade authentication flow
+---
+```
+
+- Use ISO 8601 dates for `created`.
+- Keep keys in alphabetical order.
+- `status` must match the values used in `codex/STATE.md`.
+- `priority` is one of `P0`, `P1`, `P2`, or `P3`.
+
+## Body Outline
+
+```markdown
+## Context
+
+Briefly describe the problem space and why the work matters.
+
+## Plan
+
+- [ ] Step or milestone
+- [ ] Another step
+
+## Acceptance
+
+- [ ] Condition or test that confirms success
+
+## Links
+
+- Primary PR: _(add a Markdown link when created)_
+- Follow-ups: _(list future tickets or TODOs)_
+
+## Log
+
+- 2024-01-15T10:42:00Z – Initial draft created, awaiting estimation.
+```
+
+### Best Practices
+
+- Keep the plan checklist current; mark completed items with `[x]` and expand with sub-steps when scope changes.
+- Add timestamps to every log entry in UTC using the `YYYY-MM-DDThh:mm:ssZ` format.
+- Record notable decisions, blockers, escalations, and validations in the log to build an auditable history.
+- When opening a PR, link it in both the **Links** section and the corresponding row in `codex/STATE.md`.
+- If work is descoped or postponed, document the reasoning in the log before updating the status or priority.

codex/tickets/TICKET_TEMPLATE.md

@@ -0,0 +1,31 @@
+---
+created: YYYY-MM-DD
+id: TKT-XXXX
+owner: github-handle
+priority: P1
+status: Backlog
+title: Concise, action-oriented title
+---
+
+## Context
+
+> Summarise the problem space, business justification, and any relevant background links.
+
+## Plan
+
+- [ ] Outline the primary milestones or implementation steps.
+- [ ] Add additional tasks as the plan evolves.
+
+## Acceptance
+
+- [ ] Condition that proves the work is complete.
+- [ ] Include verification steps, test coverage expectations, or sign-off requirements.
+
+## Links
+
+- Primary PR: _(add when available)_
+- Follow-ups: _(reference additional tickets or TODO items)_
+
+## Log
+
+- YYYY-MM-DDThh:mm:ssZ – First update recorded here.