From 27849b336dcf3c84f8451745cbab88b8a639ce36 Mon Sep 17 00:00:00 2001
From: David Sanchez <64162682+dsfaccini@users.noreply.github.com>
Date: Sat, 21 Mar 2026 00:30:54 -0500
Subject: [PATCH] first readme

---
 {.claude => .agents}/settings.json |  0
 .agents/settings.local.json        |  5 ++++
 .claude                            |  1 +
 README.md                          | 41 ++++++++++++++++++++++++++++++
 4 files changed, 47 insertions(+)
 rename {.claude => .agents}/settings.json (100%)
 create mode 100644 .agents/settings.local.json
 create mode 120000 .claude
 create mode 100644 README.md

diff --git a/.claude/settings.json b/.agents/settings.json
similarity index 100%
rename from .claude/settings.json
rename to .agents/settings.json
diff --git a/.agents/settings.local.json b/.agents/settings.local.json
new file mode 100644
index 0000000..8b311a3
--- /dev/null
+++ b/.agents/settings.local.json
@@ -0,0 +1,5 @@
+{
+  "permissions": {
+    "allow": []
+  }
+}
diff --git a/.claude b/.claude
new file mode 120000
index 0000000..c0ca468
--- /dev/null
+++ b/.claude
@@ -0,0 +1 @@
+.agents
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0308874
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+TODOs and plan for this repo
+
+## intro
+
+TODO
+
+## glossary
+
+AICA: AI Code Assistant
+Research: AICAs are able to do research via WebFetching, WebSearching or using the `gh` CLI to look up issues, PRs and comments on github, as well as explore code they don't locally have access to.
+
+## mechanical 
+
+- [ ] start a new python package (`pydantic-harness`)
+    - [ ] `uv init`
+
+
+## automated code factory
+
+- the optimal flow is issue gets opened and discussed -> when ready, AICA is triggered to open a PR to close the issue with only one file (`PLAN.md`)
+- `PLAN.md` is reviewed (inline comments, PR discussion) -> AICA is triggered to update the plan
+- when the plan is ready, AICA is triggered to implement the plan
+- AICA must loop to review the changes are according to the plan, identify any new questions
+    - more about looping under [ralph loop](#ralph-loop) below.
+
+### how does the AICA get triggered? via the label system
+
+We use labels to trigger AICA actions, at the end of each action AICA must remove the label that triggered it.
+
+Labels:
+- when an issue is labeled with `aica:research`, AICA is triggered to answer questions posed in the issue (body and/or comments) by researching and linking sources, emphasis on **linking sources** for every claim it makes
+- when an issue is labeled with `aica:write-plan`, AICA is triggered to create a `PLAN.md` in the issue's branch
+- when a PR is labeled with `aica:update-plan`, AICA is triggered to update the `PLAN.md` in the PR's branch according to the latest discussions in the PR
+    - note that AICA must be able to do research in this step as well before updating the plan, if any questions require it
+    - any findings and decisions made must be documented in a new PR comment, not as part of the thread
+    - the reason for this is so we can resolve threads. if we document decisions in threads, we have to keep the threads open, which bloats the PR page and creates noise for future fetches of the PR. 
+- when a PR is labeled with `aica:implement-plan`, AICA is triggered to implement the plan in `PLAN.md` in the PR's branch
+
+### ralph loop
+
+TODO
\ No newline at end of file