docs: project design document and agent working agreement - #1
Merged
Conversation
Transcribe the headless/non-interactive docs for the three coding CLIs Atlas can drive as AI backends (Claude Code, Codex, Antigravity) into Markdown, plus an index and the original Antigravity source PDF. All three support --output-format json with a JSON-schema flag, so Atlas's structured output contract maps uniformly onto every backend.
Full design for Atlas, a local-first TUI job-application co-pilot: vision, architecture (daemon + TUI client), component specs, SQLModel data model, AI task contracts, TUI/CLI surfaces, honesty controls, cross-platform support, technology stack, phased roadmap, and an appendix documenting the coding-CLI adapter invocations.
Define the contract for changing code in this repo: feature branches with conventional branch naming, Conventional Commits with one logical change each and no AI attribution, uv for project management, ruff and mypy --strict gates, 100% line and branch test coverage with isolated tests, PR review flow, and a definition of done. Symlink CLAUDE.md to it so Claude Code loads the same guidance.
Rewrite the root README with a project overview, highlights, and links to the docs, and add a docs/README.md index pointing to the design document, CLI reference, and the AGENTS.md working agreement.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds the initial documentation for Atlas (no code yet — design/pre-implementation phase):
docs/PROJECT.md— full design document: vision, architecture (background daemon + TUI client), component specs, SQLModel data model, AI task contracts, TUI/CLI surfaces, honesty controls, cross-platform support, technology stack, phased roadmap, and an appendix documenting the coding-CLI adapter invocations.docs/cli-reference/— transcribed headless-mode docs for the three coding CLIs Atlas can drive as AI backends (Claude Code, Codex, Antigravity), an index, and the original Antigravity source PDF.AGENTS.md— working agreement for anyone changing this repo: feature branches, Conventional Commits (one logical change each), uv for project management, ruff + mypy --strict gates, 100% line/branch test coverage with isolated tests, and the PR review flow.CLAUDE.mdsymlinks to it.Why
Locks down scope, architecture, and contributor conventions before implementation begins, so Phase 0 scaffolding has a clear target.
Commits (one logical change each)
docs(cli-reference): add coding CLI headless-mode referencedocs(project): add Atlas project design documentdocs: add AGENTS.md working agreement for coding agentsdocs(readme): add project overview and documentation indexTesting
Docs-only change; no code or tests affected. All internal relative links verified to resolve.
Notes for reviewer
CLAUDE.mdis a symlink toAGENTS.mdso Claude Code auto-loads the same guidance — remove if undesired.CHANGELOG.mdis referenced by the definition of done but not yet created; it can land with the first Phase 0 code.