From 736c21a3d865a7935e31b78ffe1a3c3bcf35bbf0 Mon Sep 17 00:00:00 2001 From: "Tj (bougyman) Vanderpoel" Date: Tue, 18 Aug 2026 10:06:41 -0400 Subject: [PATCH] docs(agents): document project structure and fix stale plan index Add a Project Structure section to AGENTS.md describing the two-project layout (RepoTasks root vs LinearCli app), the role of each top-level directory, the layered module architecture, data-flow through the stack, and a maintenance convention for keeping the section current. Also update the Plan index to include phase 9 (profiles), phase 10 (favorites), and phase 11 (bare issue numbers) plans, which were present in documents/ but missing from the index. Co-Authored-By: Claude Sonnet 4.6 --- AGENTS.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 69606c9..32aa08b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,6 +11,87 @@ and best practices for agents to follow. - Phase 6 Plan: documents/phase-6-plan.adoc - Phase 7 Plan: documents/phase-7-plan.adoc - Phase 8 Plan: documents/phase-8-plan.adoc +- Phase 9 Plan: documents/phase-9-plan.adoc +- Phase 10 Plan: documents/phase-10-plan.adoc +- Phase 11 Plan: documents/phase-11-plan.adoc + +## Project Structure + +### Repository layout + +This repo uses two Mix projects side-by-side, not nested: + +- `app/` — The CLI itself (`LinearCli` application, version-managed, + Burrito-released). All end-user features live here. +- `lib/`, `mix.exs` (root) — Repo-management tooling (`RepoTasks` project, + no deps). Mix tasks that operate on the repo as a whole: `mix lc`, + `mix setup`, `mix git_hooks`, `mix stokowski`, `mix container.build/publish`. + These tasks orchestrate other tools as child processes and know nothing + about `app/`'s internal modules. + +Supporting directories (not Mix projects): + +- `bin/` — Wrapper shell scripts (`lcls`, `lcreate`, `lclose`, `lcomment`, + `lproj`). Each one just calls `exec lc ...`. +- `ci/` — Shell scripts for CI and release: conventional-commit enforcement, + container build/publish, Homebrew formula bump. +- `githooks/` — `commit-msg` and `pre-push` hooks; installed by `mix setup`. +- `oci/` — `Containerfile` for the published container image. +- `schema/` — The Linear GraphQL schema (`LinearAPI.graphql`), kept for reference. +- `cinemas/` — Terminal session recordings (`.cinema.gif`) embedded in Readme.adoc. +- `.ai/prompts/` — Stokowski agent-stage prompt files (`global.md`, + `implement.md`, `investigate.md`, etc.). +- `vendor/` — Git submodules: `ash`, `oban`, `usage_rules`, `ruby-linear-cli`, + and others. Source references and local development copies, not build inputs + — the app uses Hex packages, not these. +- `documents/` — Architecture decision records and phase plans (see The Plan above). + +### App module structure (`app/lib/linear_cli/`) + +The app is organized in layers: + +``` +LinearCli.CLI — Entry point; Optimus argument parsing and dispatch + CLI.Commands — One function per subcommand; formats and prints output + CLI.IssueHelpers — Issue-lookup logic shared across subcommands + CLI.WhatFor — Interactive prompts (team, project, label selection) + CLI.Display — Output formatting helpers + CLI.Projects — Project-specific prompt/resolution helpers + CLI.Prompt — Low-level readline-style prompt wrapper + +LinearCli.Linear — Ash domain; all Linear API resources and actions + Linear.Issue/Team/... — Ash resources (actions are manual GraphQL calls) + LinearCli.Api — Thin GraphQL client (Req); the only module that + speaks to api.linear.app directly + +LinearCli.Profiles — Named team/project bundles, persisted in SQLite +LinearCli.Favorites — Favorited teams/projects, same SQLite file +LinearCli.Git — Git branch creation/detection logic +LinearCli.Rollover — Monthly issue-rollover logic (pure, no Oban dep) + Rollover.Worker — Thin Oban wrapper around Rollover.run/2 + +LinearCli.ObanRepo — Runtime adapter selector (SQLite or Postgres) + ObanRepo.Sqlite/.Postgres — Ecto repos for each backend + +LinearCli.Application — OTP Application; starts interactive or daemon mode +``` + +Data flows top-to-bottom through these layers: `CLI.Commands` calls the +`LinearCli.Linear` domain code interface; the domain's Ash resources call +`LinearCli.Api`; `LinearCli.Api` calls the Linear GraphQL API. `Profiles` +and `Favorites` are side-channels consulted by `CLI.Commands` and +`CLI.IssueHelpers` for defaults, not part of the main API data flow. + +The daemon mode (started when `LINEAR_CLI_DAEMON=true`) runs +`LinearCli.Rollover.Worker` via Oban on a monthly cron schedule. The +interactive CLI mode never starts Oban or an Ecto repo. + +### Maintenance convention + +Update this section when adding a new top-level directory, a new major module +(one that other modules depend on or that introduces a new architectural layer), +or a new phase plan document. File-level changes inside existing directories do +not need a structural-doc update. ## Standards