diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 92052cc..57dfb89 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -8,7 +8,7 @@ "name": "fastsqla", "source": { "source": "local", - "path": "./" + "path": "./plugins/fastsqla" }, "policy": { "installation": "AVAILABLE", diff --git a/.agents/skills/beads/SKILL.md b/.agents/skills/beads/SKILL.md deleted file mode 100644 index a5a3344..0000000 --- a/.agents/skills/beads/SKILL.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -name: beads -description: Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking. ---- - -# Beads - -Use Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work. - -## First Step - -Run: - -```bash -bd prime -``` - -If that prints nothing, check whether the repository has an active Beads workspace: - -```bash -bd where -``` - -## Preferred Route - -Use the `bd` CLI when shell access is available. It is the most compact and direct Beads interface. - -## Core CLI Workflow - -1. Find work: - -```bash -bd ready -bd list --status=open -bd list --status=in_progress -``` - -2. Inspect before editing: - -```bash -bd show -``` - -3. Claim work atomically: - -```bash -bd update --claim -``` - -4. Create durable follow-up work when implementation reveals new tasks: - -```bash -bd create "Short title" --description="Why this exists and what needs to be done" --type=task --priority=2 -``` - -5. Close completed work: - -```bash -bd close --reason="Completed" -``` - -## What Belongs In Beads - -Use Beads for: - -- shared project tasks -- blockers and dependencies -- discovered follow-up work -- work that must survive thread reset, compaction, or handoff -- status that another person or agent should be able to resume - -Use agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state. - -## Rules - -- Do not create markdown TODO files as the source of truth when Beads is available. -- Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead. -- Prefer `--json` when parsing `bd` output programmatically. -- If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing. -- Do not auto-close or mutate tasks unless the work is actually complete. diff --git a/.agents/skills/beads/agents/openai.yaml b/.agents/skills/beads/agents/openai.yaml deleted file mode 100644 index 09c3b8f..0000000 --- a/.agents/skills/beads/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Beads" - short_description: "Project task tracking with bd" - default_prompt: "Use $beads to inspect ready work and manage durable project tasks." diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 5690e11..1fbb661 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -9,7 +9,7 @@ "plugins": [ { "name": "fastsqla", - "source": "./", + "source": "./plugins/fastsqla", "description": "Use FastSQLA's current setup, async session, and pagination APIs correctly.", "version": "1.0.0", "author": { diff --git a/.claude/settings.json b/.claude/settings.json deleted file mode 100644 index ad64a63..0000000 --- a/.claude/settings.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "hooks": {} -} \ No newline at end of file diff --git a/.codex/config.toml b/.codex/config.toml deleted file mode 100644 index 146af7e..0000000 --- a/.codex/config.toml +++ /dev/null @@ -1,2 +0,0 @@ -[features] -hooks = true diff --git a/.codex/hooks.json b/.codex/hooks.json deleted file mode 100644 index 13c7229..0000000 --- a/.codex/hooks.json +++ /dev/null @@ -1,51 +0,0 @@ -{ - "hooks": { - "PostCompact": [ - { - "hooks": [ - { - "command": "bd codex-hook PostCompact", - "statusMessage": "Scheduling Beads context refresh", - "type": "command" - } - ], - "matcher": "manual|auto" - } - ], - "PreCompact": [ - { - "hooks": [ - { - "command": "bd codex-hook PreCompact", - "statusMessage": "Checking Beads context", - "type": "command" - } - ], - "matcher": "manual|auto" - } - ], - "SessionStart": [ - { - "hooks": [ - { - "command": "bd codex-hook SessionStart", - "statusMessage": "Loading Beads context", - "type": "command" - } - ], - "matcher": "startup|resume|clear" - } - ], - "UserPromptSubmit": [ - { - "hooks": [ - { - "command": "bd codex-hook UserPromptSubmit", - "statusMessage": "Refreshing Beads context", - "type": "command" - } - ] - } - ] - } -} diff --git a/overrides/main.html b/.github/mkdocs-overrides/main.html similarity index 100% rename from overrides/main.html rename to .github/mkdocs-overrides/main.html diff --git a/AGENTS.md b/AGENTS.md index c6b2f4c..17c7cd4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,120 +1,35 @@ # Agent Instructions -This project uses **bd** (beads) for issue tracking. Run `bd onboard` to get started. - -## Quick Reference - -```bash -bd ready # Find available work -bd show # View issue details -bd update --status in_progress # Claim work -bd close # Complete work -bd sync # Sync with git -``` - -## Landing the Plane (Session Completion) - -**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds. - -**MANDATORY WORKFLOW:** - -1. **File issues for remaining work** - Create issues for anything that needs follow-up -2. **Run quality gates** (if code changed) - Tests, linters, builds -3. **Update issue status** - Close finished work, update in-progress items -4. **PUSH TO REMOTE** - This is MANDATORY: - ```bash - git pull --rebase - bd sync - git push - git status # MUST show "up to date with origin" - ``` -5. **Clean up** - Clear stashes, prune remote branches -6. **Verify** - All changes committed AND pushed -7. **Hand off** - Provide context for next session - -**CRITICAL RULES:** -- Work is NOT complete until `git push` succeeds -- NEVER stop before pushing - that leaves work stranded locally -- NEVER say "ready to push when you are" - YOU must push -- If push fails, resolve and retry until it succeeds - - - -## Beads Issue Tracker - -This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands. - -### Quick Reference - -```bash -bd ready # Find available work -bd show # View issue details -bd update --claim # Claim work -bd close # Complete work -``` - -### Rules - -- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists -- Run `bd prime` for detailed command reference and session close protocol -- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files - -**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns. - -## Agent Context Profiles - -The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. - -- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. -- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise. -- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins. - -## Session Completion - -This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. - -1. **File issues for remaining work** - Create beads for anything that needs follow-up -2. **Run quality gates** (if code changed) - Tests, linters, builds -3. **Update issue status** - Close finished work, update in-progress items -4. **Handle git/sync by active profile**: - ```bash - # Conservative/minimal/default: report status and proposed commands; wait for approval. - git status - - # Team-maintainer opt-in only, unless current instructions forbid it: - git pull --rebase - bd dolt push - git push - git status - ``` -5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step - -**Critical rules:** -- Explicit user or orchestrator instructions override this Beads block. -- Do not commit or push without clear authority from the active profile or the current user request. -- If a required sync or push is blocked, stop and report the exact command and error. - - - -## Beads Issue Tracker - -Use Beads (`bd`) for durable task tracking in repositories that include it. Use the `beads` skill at `.agents/skills/beads/SKILL.md` (project install) or `~/.agents/skills/beads/SKILL.md` (global install) for Beads workflow guidance, then use the `bd` CLI for issue operations. - -### Quick Reference - -```bash -bd ready # Find available work -bd show # View issue details -bd update --claim # Claim work -bd close # Complete work -bd prime # Refresh Beads context -``` - -### Rules - -- Use `bd` for all task tracking; do not create markdown TODO lists. -- Run `bd prime` when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use `/hooks` to inspect or toggle them. -- Keep persistent project memory in Beads via `bd remember`; do not create ad hoc memory files. - -**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns. - +## Workflow + +- Run `bd prime` when starting work or after context compaction. +- Use Beads for durable task tracking and shared project memory. +- Read the closest applicable `AGENTS.md` before changing files. +- Inspect `git status` and existing diffs before modifying the worktree. +- Record complex implementation plans as Bead notes before coding. + +## Engineering + +- Prefer simple root-cause fixes and complete implementations. +- Preserve unrelated changes and avoid drive-by formatting. +- Fail clearly on invalid configuration; do not add plausible dummy defaults. +- Validate external input at trust boundaries and never expose secrets. +- Describe the current state in documentation and code comments. + +## Git + +- Keep one task per pull request and stay below 500 added lines. +- Work in `.worktrees/` on `feat/`, `fix/`, `chore/`, or `docs/` branches. +- Use conventional commit prefixes and do not add AI signatures. +- Use `gh` for GitHub operations. +- Scan for secrets before committing. +- Rebase on current `main` before opening a pull request. +- Do not commit or push without authority from the user or active Beads profile. + +## Verification + +- Run tests, linters, builds, and behavioral checks proportional to the change. +- Never claim completion without evidence from the relevant quality gates. +- Verify pushed commits on the remote branch. +- After a pull request merges, close its Bead, extract PR lessons, and remove its + worktree and local branch. diff --git a/CLAUDE.md b/CLAUDE.md index db14bd1..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,77 +1 @@ -# Project Instructions for AI Agents - -This file provides instructions and context for AI coding agents working on this project. - - -## Beads Issue Tracker - -This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands. - -### Quick Reference - -```bash -bd ready # Find available work -bd show # View issue details -bd update --claim # Claim work -bd close # Complete work -``` - -### Rules - -- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists -- Run `bd prime` for detailed command reference and session close protocol -- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files - -**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns. - -## Agent Context Profiles - -The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. - -- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. -- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise. -- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins. - -## Session Completion - -This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. - -1. **File issues for remaining work** - Create beads for anything that needs follow-up -2. **Run quality gates** (if code changed) - Tests, linters, builds -3. **Update issue status** - Close finished work, update in-progress items -4. **Handle git/sync by active profile**: - ```bash - # Conservative/minimal/default: report status and proposed commands; wait for approval. - git status - - # Team-maintainer opt-in only, unless current instructions forbid it: - git pull --rebase - git push - git status - ``` -5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step - -**Critical rules:** -- Explicit user or orchestrator instructions override this Beads block. -- Do not commit or push without clear authority from the active profile or the current user request. -- If a required sync or push is blocked, stop and report the exact command and error. - - - -## Build & Test - -_Add your build and test commands here_ - -```bash -# Example: -# npm install -# npm test -``` - -## Architecture Overview - -_Add a brief overview of your project architecture_ - -## Conventions & Patterns - -_Add your project-specific conventions here_ +@AGENTS.md diff --git a/context7.json b/context7.json index ae86cd8..3ebe5f5 100644 --- a/context7.json +++ b/context7.json @@ -4,7 +4,7 @@ "public_key": "pk_HGTiXpaLrQ2YW61qLOKbF", "projectTitle": "FastSQLA", "description": "Async SQLAlchemy sessions and pagination for FastAPI, with optional SQLModel support.", - "folders": ["docs", "skills"], + "folders": ["docs", "plugins/fastsqla/skills"], "excludeFiles": ["CHANGELOG.md"], "rules": [ "Configure FastAPI with fastsqla.lifespan or new_lifespan(); do not construct engines or sessions manually.", diff --git a/mkdocs.yml b/mkdocs.yml index 93fb275..b687e2d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,7 +16,7 @@ nav: - Changelog: changelog.md theme: - custom_dir: overrides + custom_dir: .github/mkdocs-overrides favicon: images/favicon.png icon: logo: material/database diff --git a/.claude-plugin/plugin.json b/plugins/fastsqla/.claude-plugin/plugin.json similarity index 100% rename from .claude-plugin/plugin.json rename to plugins/fastsqla/.claude-plugin/plugin.json diff --git a/.codex-plugin/plugin.json b/plugins/fastsqla/.codex-plugin/plugin.json similarity index 100% rename from .codex-plugin/plugin.json rename to plugins/fastsqla/.codex-plugin/plugin.json diff --git a/skills/fastsqla-pagination/SKILL.md b/plugins/fastsqla/skills/fastsqla-pagination/SKILL.md similarity index 100% rename from skills/fastsqla-pagination/SKILL.md rename to plugins/fastsqla/skills/fastsqla-pagination/SKILL.md diff --git a/skills/fastsqla-session/SKILL.md b/plugins/fastsqla/skills/fastsqla-session/SKILL.md similarity index 100% rename from skills/fastsqla-session/SKILL.md rename to plugins/fastsqla/skills/fastsqla-session/SKILL.md diff --git a/skills/fastsqla-setup/SKILL.md b/plugins/fastsqla/skills/fastsqla-setup/SKILL.md similarity index 100% rename from skills/fastsqla-setup/SKILL.md rename to plugins/fastsqla/skills/fastsqla-setup/SKILL.md