docs: README/STATUS refresh for coordination layer + prior pending commits

[getappz]

Summary

• Repositions the README to reflect agentflare's actual current scope: the optimization layer (lean-ctx, memory, Caveman, Ponytail) plus the multi-agent coordination layer that's grown since (work items, review, artifacts, handoff, coaching, MCP surface).
• Adds an explicit Beta status banner + STATUS.md splitting stable vs. actively-changing surface, including a documented gap in update.rs/install.sh (string-inequality version comparison, not semver).
• Stops tracking docs/ (10 internal planning docs, ~5,175 lines) that were committed by accident; moved to a new gitignored .docs/ dir, kept on disk, existing git history untouched.
• Also carries 3 previously-unpushed local commits on master (SessionStart systemMessage visibility fix, refresh-install -Task requirement).

Test plan

• CI status checks pass
• README renders correctly on GitHub (tables, badges, links to STATUS.md)
• .docs/ is gitignored and does not appear in the diff

Summary by CodeRabbit

• Documentation

  • Updated product documentation to reflect Beta status and describe multi-agent coordination capabilities.
  • Added a project status guide covering stable features, changing areas, and known limitations.
  • Removed several outdated architecture, product, security, testing, deployment, and API reference documents.

• Improvements

  • Session-start hooks now return structured JSON with system messaging and additional context.
  • Installation refresh scripts can target a specific worktree and provide clearer errors for ambiguous selections.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR marks agentflare as Beta, documents its optimization and coordination layers, adds status guidance, removes legacy documentation, improves worktree-based installation selection, and changes session-start hooks to emit structured JSON.

Changes

Documentation and repository metadata

Layer / File(s)	Summary
Beta status and documentation updates README.md, STATUS.md, docs/*.md	The README documents Beta status, coordination capabilities, benchmark scope, and updated architecture modules; STATUS.md records stability categories and known gaps; legacy documentation files are removed.
Documentation ignore pattern .gitignore	The ignore rule now covers /.docs/ instead of /docs/superpowers/.

Worktree-aware installation

Layer / File(s)	Summary
Worktree resolution and installation scripts/refresh-install.ps1	The script accepts -Task, enumerates Git worktrees, selects a unique matching worktree, validates errors, and installs from the resolved path.

Structured session-start hook output

Layer / File(s)	Summary
Session-start JSON response src/hook.rs	session_start emits JSON containing systemMessage and hookSpecificOutput.additionalContext with the generated session message.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Possibly related PRs

• getappz/agentflare#98: Updates tracking for documentation files related to the ignore-rule changes.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title reflects the README/STATUS docs refresh and related local commits, though it is somewhat broad.
Description check	✅ Passed	The PR description covers Summary and Test plan, with only the Notes for reviewers section missing.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ship-pending-master-work

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

scripts/refresh-install.ps1 (1)

9-50: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

-Task is silently ignored when already inside a worktree.

The entire worktree-resolution/matching block is only entered when .git is a directory (i.e., running from the main repo root). If a caller runs the script from inside a linked worktree and passes -Task <other-worktree>, that block is skipped and the script silently installs from the current worktree instead of the one named by -Task — no warning or error is raised. Given this installs a system binary (cargo install --force), silently installing from the wrong worktree could be confusing.

Consider at least warning when -Task is supplied but not applied because the script is already inside a worktree, or extending the matching logic to also apply when -Task is set regardless of current location.

♻️ Example: warn when `-Task` is ignored

+if ($Task -and -not (Test-Path (Join-Path $root ".git") -PathType Container)) {
+  Write-Warning "[refresh-install] Already inside a worktree ($root); ignoring -Task '$Task'."
+}
 if (Test-Path (Join-Path $root ".git") -PathType Container) {

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/refresh-install.ps1` around lines 9 - 50, Ensure the -Task selection
is handled whenever -Task is supplied, including when the script is launched
from inside a linked worktree. Update the worktree-resolution logic around the
$Task matching block so it either resolves the requested worktree regardless of
the current location or explicitly warns and exits when -Task cannot be applied;
never silently continue using the current worktree.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@scripts/refresh-install.ps1`:
- Around line 9-50: Ensure the -Task selection is handled whenever -Task is
supplied, including when the script is launched from inside a linked worktree.
Update the worktree-resolution logic around the $Task matching block so it
either resolves the requested worktree regardless of the current location or
explicitly warns and exits when -Task cannot be applied; never silently continue
using the current worktree.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 58525544-17f6-4203-9674-de089045ee6d

📥 Commits

Reviewing files that changed from the base of the PR and between 342c4c3 and 1bfd45b.

📒 Files selected for processing (15)

• .gitignore
• README.md
• STATUS.md
• docs/api-sdk-reference.md
• docs/architecture-system-design.md
• docs/business-overview.md
• docs/data-model.md
• docs/deployment-and-operations.md
• docs/feature-agent-lifecycle-cli.md
• docs/feature-caam-auth-vault.md
• docs/product-overview.md
• docs/security.md
• docs/testing.md
• scripts/refresh-install.ps1
• src/hook.rs

💤 Files with no reviewable changes (10)

• docs/architecture-system-design.md
• docs/security.md
• docs/feature-agent-lifecycle-cli.md
• docs/deployment-and-operations.md
• docs/api-sdk-reference.md
• docs/testing.md
• docs/business-overview.md
• docs/data-model.md
• docs/product-overview.md
• docs/feature-caam-auth-vault.md