From 6dddc7d6b4fed8277be1880a7c383909a19fc956 Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 17 Sep 2025 08:59:16 -0500 Subject: [PATCH] chore: add collab/ structure; move questions; add AGENTS.md; addendum in SeedPrompt.md --- AGENTS.md | 35 +++++++++++++++++++ SeedPrompt.md | 13 ++++++- collab/00-bootstrap-plan.md | 11 ++++++ collab/00-bootstrap-proposal.md | 20 +++++++++++ .../00-bootstrap-questions.md | 8 ++--- devlog/DEVLOG_HUMAN.md | 15 ++++++++ devlog/DEVLOG_LLM.md | 12 +++++++ 7 files changed, 108 insertions(+), 6 deletions(-) create mode 100644 AGENTS.md create mode 100644 collab/00-bootstrap-plan.md create mode 100644 collab/00-bootstrap-proposal.md rename QUESTIONS.md => collab/00-bootstrap-questions.md (83%) diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..51c51ff --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,35 @@ +# AGENTS.md — Working Agreements and Conventions + +Scope: Applies to the entire repository unless overridden by a deeper AGENTS.md. + +## Collaboration Artifacts +- Directory: `collab/` +- Naming: `-.md` + - Examples: `00-bootstrap-questions.md`, `01-wrapper-proposal.md`, `01-wrapper-plan.md` +- Types: `questions`, `proposal`, `plan` +- Principle: Keep chat minimal; prefer file-based collaboration via these documents. + +## Logs and Documentation +- Dev logs: `devlog/DEVLOG_LLM.md` and `devlog/DEVLOG_HUMAN.md` updated each meaningful change. +- Project docs: `docs/` for feature docs (`.md`) and architectural decisions (`adr-.md`). +- README: Keep `README.md` current with quickstart and usage. + +## Code and Tests +- Add unit tests in `tests/` alongside features as they are introduced. +- Keep changes minimal and focused. Avoid unrelated refactors. + +## Git Workflow +- Branch: work on `main` for now. +- Commits: concise, present-tense; Conventional Commits style preferred (e.g., `feat:`, `fix:`, `chore:`). +- Releases/Tags: `YYYY-MM-DD-HHMM` when warranted; use `tea` if configured. + +## Wrapper Project Guidelines +- Aim: Bash wrapper around `codex-cli` with modes (global prompt, mode prompt, project prompt, codex settings, MCP). +- Approach: crawl → walk → run. Start with documented defaults and override via flags/env/config. +- Wizards: Intake markdown forms for creating modes and projects. + +## Agent Notes +- Ask clarifying questions in `collab/<...>-questions.md`. +- Propose in `collab/<...>-proposal.md`, plan in `collab/<...>-plan.md`, then implement. +- Respect repository structure and this AGENTS.md across all changes. + diff --git a/SeedPrompt.md b/SeedPrompt.md index 570843b..a5d9cf3 100644 --- a/SeedPrompt.md +++ b/SeedPrompt.md @@ -33,4 +33,15 @@ This should be very collaborative. Ask questions (in a markdown file), once they I want to be able to test the code early/often and be able to provide feedback. I want to be able to edit markdown files inline to provide context/ask questions etc as we go. The chat interface itself should be kept very clean as it's running in the bottom of my vscode instance and I want to use vscode markdown facilities to rapidly read/edit the markdown files. So our primary way of interacting will be via those files. -Commit/push everything in the repo now before we get started on the project. \ No newline at end of file +Commit/push everything in the repo now before we get started on the project. + +--- + +## Addendum (Housekeeping) — 2025-09-17 + +- Create and use a `collab/` directory for coordination artifacts. +- Use consistent filenames: `-.md` where `` is one of `questions`, `proposal`, `plan`. +- Move any existing questions into `collab/` following the naming scheme (e.g., `00-bootstrap-questions.md`). +- Create and maintain an `AGENTS.md` at the repo root with working agreements and conventions. +- Continue keeping `devlog/DEVLOG_LLM.md` and `devlog/DEVLOG_HUMAN.md` updated. +- After applying this structure, commit and push the changes. diff --git a/collab/00-bootstrap-plan.md b/collab/00-bootstrap-plan.md new file mode 100644 index 0000000..bf2103b --- /dev/null +++ b/collab/00-bootstrap-plan.md @@ -0,0 +1,11 @@ +# 00 — Bootstrap — Plan + +1. Create `collab/` directory for coordination artifacts. +2. Move `QUESTIONS.md` to `collab/00-bootstrap-questions.md`. +3. Add `collab/00-bootstrap-proposal.md` and this plan file. +4. Create `AGENTS.md` capturing repository working agreements. +5. Append Addendum to `SeedPrompt.md` describing the new structure. +6. Commit and push changes to `main`. + +Status: pending review/confirmation. + diff --git a/collab/00-bootstrap-proposal.md b/collab/00-bootstrap-proposal.md new file mode 100644 index 0000000..3d6605b --- /dev/null +++ b/collab/00-bootstrap-proposal.md @@ -0,0 +1,20 @@ +# 00 — Bootstrap — Proposal + +Purpose: Formalize the collaboration scaffolding and initial workflow. + +Scope: +- Use `collab/` directory to host questions, proposals, and plans. +- Adopt filename pattern: `-.md`, where `` ∈ {`questions`, `proposal`, `plan`}. +- Maintain `AGENTS.md` with working conventions and agent guidance. + +Deliverables (this step): +- collab/00-bootstrap-questions.md (moved from root) +- collab/00-bootstrap-proposal.md (this file) +- collab/00-bootstrap-plan.md (skeleton) +- AGENTS.md (initial content) +- SeedPrompt.md updated with an Addendum describing this structure + +Acceptance Criteria: +- Repo contains the above files with agreed naming scheme. +- CI not required; manual review suffices for this step. + diff --git a/QUESTIONS.md b/collab/00-bootstrap-questions.md similarity index 83% rename from QUESTIONS.md rename to collab/00-bootstrap-questions.md index 8f828aa..7a8f3e2 100644 --- a/QUESTIONS.md +++ b/collab/00-bootstrap-questions.md @@ -1,9 +1,9 @@ -# Open Questions +# 00 — Bootstrap — Questions -These questions will guide the initial design and implementation. Please answer inline. +These questions guide the initial design and implementation. Please answer inline. ## Repo & workflow -1. Git remote: Should we push to an existing remote? If yes, please provide the remote URL and branch (default `origin main`). +1. Git remote: Should we push to an existing remote? If yes, provide the remote URL and branch (default `origin main`). 2. Tagging: Use `YYYY-MM-DD-HHMM` in local time or UTC? Use `tea` only for tagging/releases, or also for pushes? 3. Commit cadence: Any specific commit style (e.g., Conventional Commits)? @@ -29,5 +29,3 @@ These questions will guide the initial design and implementation. Please answer 16. Licensing/headers: Any repo-specific requirements beyond the existing LICENSE? 17. Supported OS/shells: Target bash/zsh on macOS/Linux, anything else? -Once answered, I will draft a concise proposal and then a concrete implementation plan for review. - diff --git a/devlog/DEVLOG_HUMAN.md b/devlog/DEVLOG_HUMAN.md index 91bbe3e..b26ee66 100644 --- a/devlog/DEVLOG_HUMAN.md +++ b/devlog/DEVLOG_HUMAN.md @@ -17,3 +17,18 @@ Next Steps: Notes: - Tagging a release and using `tea` is deferred until we have a first runnable wrapper or as directed. +--- + +Date: 2025-09-17 09:05 (UTC) + +Summary: +- Introduced `collab/` directory and moved QUESTIONS into `collab/00-bootstrap-questions.md`. +- Added `collab/00-bootstrap-proposal.md` and `collab/00-bootstrap-plan.md`. +- Created `AGENTS.md` with working conventions. +- Appended housekeeping Addendum to `SeedPrompt.md`. + +Details: +- Establishes consistent file-based collaboration area and naming scheme. + +Next Steps: +- Await answers to bootstrap questions, then draft proposal and plan for wrapper. diff --git a/devlog/DEVLOG_LLM.md b/devlog/DEVLOG_LLM.md index c3cb33b..09352af 100644 --- a/devlog/DEVLOG_LLM.md +++ b/devlog/DEVLOG_LLM.md @@ -13,3 +13,15 @@ This log is concise and structured for quick machine parsing and summarization. - Await answers in `QUESTIONS.md` - Draft proposal and implementation plan once clarified +## 2025-09-17T09:05Z +- context: Housekeeping structure introduced +- actions: + - Created `collab/` directory and moved questions to `collab/00-bootstrap-questions.md` + - Added `collab/00-bootstrap-proposal.md` and `collab/00-bootstrap-plan.md` + - Added `AGENTS.md` + - Appended housekeeping Addendum to `SeedPrompt.md` +- decisions: + - Adopt filename pattern `-.md` for collab artifacts +- next: + - Await answers in `collab/00-bootstrap-questions.md` + - Then fill proposal/plan and proceed to implementation