Skip to content

docs(spec-loop): refresh plan and add .apache-magpie-local hybrid-setup convention#841

Merged
potiuk merged 2 commits into
apache:mainfrom
justinmclean:plan-0712
Jul 12, 2026
Merged

docs(spec-loop): refresh plan and add .apache-magpie-local hybrid-setup convention#841
potiuk merged 2 commits into
apache:mainfrom
justinmclean:plan-0712

Conversation

@justinmclean

Copy link
Copy Markdown
Member

Summary

Two things in one plan-maintenance PR:

  1. Refresh IMPLEMENTATION_PLAN.md against main (main at fix(release): produce a clean source-only tarball and gate it in verify-rc #829). The
    committed plan was stale (it still listed the shipped education
    restructure as planned). Reconciled In-flight/shipped/planned by artifact
    on main, not branch ancestry: dropped merged items, listed the 12
    current in-flight branches, and added the ai-tutors regenerate and
    discoverability items.

  2. Record the .apache-magpie-local/ personal-override convention in
    specs/adoption-and-setup.md (acceptance 5) plus a one-shot
    "use framework defaults this run" switch (acceptance 6), with matching
    build items (magpie-local-convention, override-bypass-one-shot) and
    three hybrid-setup how-to items in the plan.

hanks to Paul King for the hybrid-setup use cases that motivated the
convention: teams where some members use Magpie and others do not, mixing
committed project overrides with per-person defaults (including temporarily
falling back to the framework default), per-role capability/MCP access (a
release manager enabling a Policy MCP others leave off), and using Magpie
against a repo that has not adopted it. Paul's insight that a semi-standard
gitignored "local"/"scratch" directory could unlock these is exactly the
missing primitive: today the only shared override surface,
.apache-magpie-overrides/, is committed, so there is nothing per-person.
.apache-magpie-local/ is that gitignored sibling, read under the same
additive-only, cannot-weaken-safety guardrail, with precedence
personal-local -> committed -> organization -> framework default.

Once the surface exists, most of the hybrid scenarios become conventions and
how-tos rather than bespoke features, which is why items 5-7 are documentation
blocked on the one foundational build item (item 3).

Type of change

  • Skill change (.claude/skills/<name>/) — eval fixtures updated below
  • Tool / bridge contract (tools/<system>/*.md)
  • Python package (tools/*/ with pyproject.toml)
  • Groovy reference impl
  • Cross-cutting (RFC, AGENTS.md, sandbox, privacy-LLM)
  • Documentation (docs/, README.md, CONTRIBUTING.md)
  • Project template (projects/_template/)
  • CI / dev loop (prek, workflows, validators)
  • Other:

Test plan

  • prek run --all-files passes
  • For Python packages touched: uv run pytest / ruff check / mypy passes
  • For Groovy bridges touched: command-line invocation tested end-to-end
  • For skill changes: eval suite passes for the affected skill
    (PYTHONPATH=tools/skill-evals/src python3 -m skill_evals.runner tools/skill-evals/evals/<skill>/)
  • For skill behaviour changes: a new or updated eval fixture is included in this PR
    (a regression test for the bug fixed / the behaviour added — see CONTRIBUTING.md)
  • Other:

@justinmclean justinmclean self-assigned this Jul 12, 2026

@potiuk potiuk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs refresh; fixed the failing markdownlint MD049 (underscore→asterisk emphasis in IMPLEMENTATION_PLAN.md). Approving.

@potiuk potiuk merged commit 1e0c75e into apache:main Jul 12, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants