Release 1.0.0

Author: Ichbinsoftware

.claude/agents/acf-context-agent.md

@@ -0,0 +1,8 @@
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

.codex/agents/acf-context-agent.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Rickard (ichbinsoftware)
+
+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.

.cursor/agents/acf-context-agent.md

@@ -0,0 +1,37 @@
+# Limitations & Honest Caveats
+
+ACF is a useful framework, but it has limitations worth understanding before you invest in it.
+
+---
+
+## The framework is only as good as what the agent can infer
+
+Stage 1 (Onboard) asks the `acf-context-agent` to scan your repository and produce an accurate architecture overview. If your codebase is inconsistent, undocumented, or structurally messy, the generated docs will reflect that. A well-structured document describing a poorly-structured system is better than nothing — but it's not the force multiplier the framework promises.
+
+**What this means in practice:** Run Stage 1 on a reasonably coherent codebase. If your repo is in poor shape, consider a basic cleanup before onboarding.
+
+---
+
+## ADC discipline still requires team buy-in
+
+The generated `AGENTS.md` tells agents when to create an ADC and how to do it. When an agent is executing a task, it will recognise when an ADC is warranted and produce one. However, there is no CI hook or PR check that enforces this for human-authored changes. If a developer ships a significant architectural change without involving an agent, no ADC will be created.
+
+**What this means in practice:** ADC coverage is strongest when agents are doing the work. For human-only changes, a PR review checklist is the most practical enforcement mechanism.
+
+---
+
+## The Review stage (Stage 4) requires an independent perspective
+
+Stage 4 asks you to review the generated documentation without anchoring to the assumptions of the agent that wrote it. The original design required a different model entirely, but the real requirement is independence — not a specific provider.
+
+In practice, a fresh session with the same model eliminates confirmation bias — the model can no longer validate what it previously wrote — and is sufficient for most teams. Switching to a different provider (Gemini, GPT-4o, etc.) gives maximum independence but is optional.
+
+**What this means in practice:** Start a new conversation and run Stage 4 from there. This costs nothing and removes confirmation bias. A different provider is better, but a fresh session is good enough.
+
+---
+
+## Stage 5 (Update) only runs when someone schedules it
+
+Architectural drift is a slow process. Stages 1–4 are not re-run — Stage 5 is the only maintenance path. The framework provides this stage but has no automated trigger. If Stage 5 isn't wired into a recurring workflow, docs will quietly fall behind the codebase and erode trust in the context layer.
+
+**What this means in practice:** Schedule it explicitly — after significant sprints or releases is a good default. A CI scheduled job, a recurring calendar reminder, or a sprint ritual all work. Do not rely on memory. An undocumented codebase is recoverable; a documentation layer that confidently describes the wrong system is worse than nothing.

.gemini/agents/acf-context-agent.md

@@ -0,0 +1,54 @@
+# When ACF Works Best
+
+ACF delivers the most value in specific conditions. Understanding where it fits — and where it doesn't — will save you from investing in the wrong place.
+
+---
+
+## It works best on legacy codebases with no documentation and no existing agent integration
+
+This is the highest-value scenario. A legacy codebase with no architecture docs and no AI tooling set up is exactly where ACF delivers the most immediate, tangible return: there's nothing to migrate from, no existing conventions to reconcile, and no agent context to replace.
+
+The `acf-context-agent` generates the entire documentation layer from scratch — architecture overview, deep-dive docs, agent instruction files — directly from the codebase. The team doesn't author anything from scratch. They trigger the agent, review what it produces, and start benefiting immediately.
+
+For teams in this position, ACF is the fastest path from zero context to a working, agent-ready documentation layer. 
+
+It works equally well on active codebases that have simply never prioritised documentation.
+
+---
+
+## It works best when agents and developers work together
+
+Developers and agents collaborate most effectively when agents have the context to make good decisions and developers have the confidence to trust and extend what agents produce. ACF provides that shared foundation — developers don't have to constantly correct agents, and agents don't have to guess at patterns and conventions.
+
+Even small amounts of context (starting at Level 1) improve the day-to-day experience. The value compounds as agent involvement deepens.
+
+---
+
+## It is a prerequisite for safe agentic DevOps
+
+As agents move from suggestions to autonomous execution — resolving incidents, migrating systems, raising PRs independently — the risk of operating without architectural context increases dramatically. An agent that doesn't know your auth pipeline, your shared contracts, or your risk triggers isn't just unhelpful, it's dangerous.
+
+For teams moving toward agentic DevOps, ACF is not optional — it's the safety layer.
+
+---
+
+## It is particularly valuable for legacy modernisation
+
+When AI agents help migrate or modernise legacy systems, the biggest risk isn't the technology — it's institutional knowledge loss. Legacy code is full of decisions that made sense at the time: workarounds for vendor limitations, tradeoffs made under constraints that no longer exist, patterns that can't be changed without breaking downstream consumers.
+
+ADCs capture this context before it's lost in translation. Without them, an AI agent will modernise the code and delete the memory.
+
+---
+
+## It is tool-agnostic by design
+
+ACF is markdown in your repo. It works with Claude Code, GitHub Copilot, Gemini CLI, Cursor, Codex, and any future tool that reads file context. You're not buying into a platform or a vendor — you're building a documentation asset that compounds over time.
+
+---
+
+## It does not work well when
+
+- The codebase has no coherent structure for the agent to infer from — Stage 1 will produce weak output
+- There is no buy-in from the team — one person maintaining ADCs for a team that ignores them is wasted effort
+- AI agents are only used for trivial, low-risk tasks where context doesn't affect output quality
+- There is no capacity to run Stage 5 periodically — docs will drift and erode trust in the framework