From a12c7732e62b3f4607722c5ee1459ebaf2a4d90e Mon Sep 17 00:00:00 2001 From: jtmorris Date: Fri, 15 May 2026 16:47:02 -0700 Subject: [PATCH] chore: add MIT license, README, and agent scaffolding --- AGENTS.md | 10 +++++ LICENSE | 21 +++++++++ README.md | 0 docs/agents/domain.md | 56 ++++++++++++++++++++++++ docs/agents/repo-instructions.md | 75 ++++++++++++++++++++++++++++++++ 5 files changed, 162 insertions(+) create mode 100644 AGENTS.md create mode 100644 LICENSE create mode 100644 README.md create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/repo-instructions.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8aea332 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,10 @@ +## Repo & agent configuration + +This project follows the full agent workflow: +initialize-project → interrogate → to-prd → to-issues → tdd + +### Repo instructions +See `docs/agents/repo-instructions.md`. + +### Domain documentation +See `docs/agents/domain.md`. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..5ed88d2 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 jtmorris + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..fdf3c42 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,56 @@ +# Domain Documentation + +This project follows the domain documentation conventions used by the `interrogate` skill. + +## Expected Layout + +### Single-context (most common) +``` +/ (project root) +├── CONTEXT.md ← canonical glossary and domain model +├── docs/ +│ └── adr/ ← Architectural Decision Records +│ ├── 0001-....md +│ └── ... +└── src/ (or equivalent) +``` + +### Multi-context (monorepos or large systems) +``` +/ (project root) +├── CONTEXT-MAP.md ← points to per-context locations +├── docs/ +│ └── adr/ ← system-wide ADRs +├── src/ +│ ├── context-a/ +│ │ ├── CONTEXT.md +│ │ └── docs/adr/ +│ └── context-b/ +│ ├── CONTEXT.md +│ └── docs/adr/ +``` + +## Rules for Skills and Agents + +### Lazy Creation +- Only create `CONTEXT.md` when the first meaningful term is resolved. +- Only create `docs/adr/` (or per-context ADR folders) when the first ADR is actually needed. +- Do not pre-create empty files "just in case". + +### During Work (especially with `interrogate`) +- When a term is used that conflicts with existing language in `CONTEXT.md`, call it out immediately. +- When vague or overloaded terms appear, propose a precise canonical term. +- Stress-test domain relationships with concrete scenarios. +- Cross-check stated behavior against actual code. +- **Update `CONTEXT.md` inline** as decisions are made — do not batch updates. + +### Architectural Decision Records (ADRs) +Only propose creating an ADR when **all three** are true: +1. The decision is hard to reverse later. +2. A future reader would be surprised without the context. +3. There were genuine alternatives and a real trade-off was made. + +Use the format defined in your project's ADR template when creating one. + +## For Other Skills +Skills such as `interrogate`, `to-prd`, architecture review, diagnosis, and TDD should read this file (and the referenced `CONTEXT.md` / ADRs) to maintain consistent domain language across the project. diff --git a/docs/agents/repo-instructions.md b/docs/agents/repo-instructions.md new file mode 100644 index 0000000..c5365fd --- /dev/null +++ b/docs/agents/repo-instructions.md @@ -0,0 +1,75 @@ +# Repo Instructions — Forgejo + +**Primary host**: https://forgejo.jtmorris.net (self-hosted Forgejo) +**CLI**: `fj` (https://codeberg.org/forgejo-contrib/forgejo-cli) + +## CLI Usage + +Assume `fj` is installed and authenticated. + +### Authentication +- `fj auth login` — interactive login (recommended first time). +- For self-hosted instances, use the `--host` flag when not inside a matching git repo: + ```bash + fj --host https://git.example.com auth login + ``` + +`fj` will often auto-detect the instance from the current git remote. + +### Common Operations + +**Issues** +```bash +fj issue create --title "..." --body "..." +fj issue list +fj issue view +fj issue comment --body "..." +``` + +**Pull Requests / Changes** +```bash +fj pr create +fj pr list +fj pr merge +``` + +For AGit-style pull requests (no fork required on many Forgejo instances), `fj` supports the normal flow. + +**Repository** +```bash +fj repo create ... +fj release create ... +``` + +### Self-Hosted / Private Instances + +When working with a private Forgejo instance that is not the default detected remote, always include `--host`: + +```bash +fj --host https://forgejo.jtmorris.net issue create ... +``` + +Store the base URL in team documentation or your shell aliases if used frequently. + +## Work Tracking Approach + +- Use the Forgejo issue tracker for most planned work, bugs, and feature requests. +- For quick local exploration or solo spikes, you may use a `.scratch/` directory (see Local section below). +- Link commits and PRs to issues using conventional references (e.g. `Fixes #123`). + +## Local / Air-Gapped / No-Remote Mode + +Even on a Forgejo-hosted project, you can work fully locally: + +- Use `git` normally. +- Track temporary work in `.scratch//` as markdown files. +- When ready, push and create issues/PRs via `fj`. + +If this project is used in a completely local-only or air-gapped context, refer to the Local template or update this file. + +## Notes for Agent Skills + +- Prefer `fj` commands when interacting with issues or PRs on this project. +- For self-hosted instances, include `--host` in commands unless the git remote already points at the correct instance. +- `interrogate` and `to-prd` should read this file to know which CLI and host conventions to follow. +- When in doubt about the current instance, check `git remote -v` first.