refactor: improve context reuse and actionable Skill workflows

.gitignore

@@ -17,3 +17,10 @@ website/__pycache__/
 
 # Local interaction journal; roadmap snapshots use .beads/issues.jsonl
 /.beads/interactions.jsonl
+
+# Local embedded Beads state; keep issues.jsonl and shared configuration eligible
+/.beads/embeddeddolt/
+/.beads/backup/
+/.beads/.local_version
+/.beads/last-touched
+/.beads/metadata.json

AGENTS.md

@@ -67,7 +67,7 @@ clean develop@SHA -> verified generated tree -> generated-only PR -> main (squas
 - Research/non-behavioral tasks use verifiable deliverables. NFRs need approved metric/target/unit, workload/window, environment and method; missing targets unresolved, N/A justified.
 - Skill procedure: intent -> verified inputs/permissions -> action -> observable result -> named next Skill with inputs, or exact prerequisite to resume.
 - Keep Skills host-neutral; isolate host-specific details in integration resources; avoid duplicating full phase procedures here.
-- Follow [common output](skills/cycle/references/common-output.md) and the current phase contract: seven-field final report, owned/preserved paths, actual versus proposed actions.
+- Follow [common output](skills/cycle/references/common-output.md) and the current phase contract: five-section final report, owned/preserved paths, actual versus proposed actions.
 - At handoff include a fenced YAML state card and copy-ready restart prompt; separate immediate_action from conditional_next_phase.
 - Recommend a fresh session for independent objectives, repository changes, stale hypotheses, major research/build handoffs or judge separation; a commit/compaction alone does not require one.
 - Keep related implementation/tests/corrections together; report proposed session name/goal and actual action. No automatic launch or new permission from handoffs.

CONTRIBUTING.md

@@ -77,7 +77,24 @@ The candidate binds the exact source commit/tree and rejects dirty or untracked
 source and uncommitted operational resources. `project` remains a working-tree
 preview. Both keep `release_ready=false`: integrity is not review or installation
 approval. Verify candidate hashes after isolated Git install/update and before
-publication. These commands never publish or mutate branches.
+publication. The opt-in real-host probe uses disposable HOME, XDG and Goose
+roots and a local Git transport repository; it never replaces a live installation:
+
+```sh
+python3 -B tests/probe_goose_distribution.py /absolute/new/product
+```
+
+The probe requires Goose 1.47.0, checks the exact seven Skills with
+`goose skills list` after installation and update, verifies installed payload
+hashes and observer execution, and confirms that update removes an obsolete
+fixture. Working-tree previews are diagnostic evidence, not committed-source
+or release approval. This probe is not part of the automatic unit suite.
+
+Production excludes creator eval sets, evaluation/conformance fixtures and
+synthetic study inputs, including those nested under Skill resources. Unknown
+nested `SKILL.md*` entrypoints fail closed; suffixes such as `.fixture` are not
+a reliable discovery boundary. Operational references and user output templates
+remain contained and available. These commands never publish or mutate branches.
 
 ## Distribution status and limits
 

README.md

@@ -24,6 +24,10 @@ Seven reusable Skills guide the work:
 Use the whole cycle or the phase your task needs. These are agent instructions,
 not an enforcement engine or a guarantee of correct software.
 
+Install: `goose plugin install https://github.com/bioinfornatics/agentic-development.git`.
+Check: `goose skills list` — only this plugin’s seven Skills, no evaluation fixtures.
+Update: `goose plugin update agentic-development`. See [Goose Plugins](https://goose-docs.ai/docs/guides/context-engineering/plugins) and [Agent Skills](https://goose-docs.ai/docs/guides/context-engineering/using-skills).
+
 ## Dependencies and workflow tools
 
 The Skills are Markdown instructions: use an agent that can load them and your

docs/cycle.md

@@ -7,15 +7,17 @@ Do not create one task per file or per phase.
 
 | Stage | Action | Expected output |
 |---|---|---|
-| Research | Explore sources and test hypotheses | Question, facts, options and unknowns |
+| Research | Establish product context before planning, then explore relevant sources | Purpose, users/outcome, current behavior, constraints, facts and unknowns |
 | Plan | Define scope, criteria, ownership and verification | Executable plan, dependencies and permissions |
 | Implement | Make the smallest coherent change | Explained diff, preserved work and targeted tests |
 | Test | Run checks on the identified candidate | Commands, results, environment and limits |
 | Judge | Compare evidence, requirements and standards | Verdict, findings, applicable score and independence |
 | Iterate | Correct a defect or resolve a prerequisite | Bounded correction and evidence to rerun |
 
+Begin every new development objective with Research, even for a clear request or familiar code.
+Research → Plan → Implement (RPI) prevents plans from relying on unchecked product assumptions.
 The coordinator chooses the next step and finalizes traceability.
-Reuse research or a plan that is still valid. Do not restart the whole cycle
+Reuse research only after checking its context coverage and freshness; reuse a plan that is still valid. Do not restart the whole cycle
 on every resumption, but do not skip a necessary check.
 
 ## Develop with rapid feedback
@@ -32,18 +34,21 @@ A documentation-format check does not prove agent behavior.
 
 ## Read each stage's report
 
-The final report always uses these seven fields, in order:
-1. **step**: the phase actually performed.
-2. **modified files**: changed paths, or N/A when none changed.
-3. **next step**: the recommended phase, loop again, blocked or done.
-4. **current goal**: the short objective addressed.
-5. **next goal**: the next objective or missing prerequisite.
-6. **closed tasks**: confirmed closed task IDs, or N/A.
-7. **explanation**: what was done and why, evidence, limits and next gate.
-
-Labels remain fixed; values are written in the user's language. The explanation
-retains relevant Goals/Non-goals, criteria, checks, verdict and session details.
-A blocked result or unchanged phase still uses all seven fields.
+The final report uses five sections, in order:
+1. **current goal {step: …}**: the outcome addressed and actual phase, with the verified task ID.
+2. **roadmap position**: verified roadmap/epic/US references, a compact cycle visual, next action and blocker/status.
+3. **modified files**: changed paths, or N/A when none changed.
+4. **closed tasks**: confirmed closed task IDs, or N/A.
+5. **explanation**: what was done and why, evidence, limits and next gate.
+
+States such as blocked, done and loop again are not phases; keep them in roadmap position.
+Do not invent roadmap progress. If it is unavailable, say so and show known cycle progress only.
+For example: `Research [reused] → Plan [active] → Implement [pending] → Test [pending] → Judge [pending]`.
+The roadmap describes outcomes; the cycle describes phases. Explain nonstandard transitions with current proof or missing prerequisites.
+Labels remain fixed; values use the user's language. Preserve relevant Goals/Non-goals, criteria, checks and verdict in explanation.
+Blocked and unchanged results still use all five sections.
+
+Read requirements before the actions they govern. Read the common output and phase delivery contracts after investigation, before drafting the response.
 
 A proposed commit has no hash. A recommended session has not been launched.
 The report distinguishes modified files from files actually committed.

hooks/README.md

@@ -26,7 +26,7 @@ These hooks block nothing: they create no commit,
 branch, task, session or Entire checkpoint. They do not validate acceptance.
 
 The Stop diagnostic still checks legacy six numbered checkpoint headings. It does
-not recognize or validate the Skills' mandatory seven-field final report. A missing
+not recognize or validate the Skills' mandatory five-section final report. A missing
 legacy shape is not a failed Skill delivery, a blocking decision or an acceptance
 verdict. Updating this diagnostic is separate runtime work.
 

integration/evals.json

@@ -20,7 +20,7 @@
         "Test evidence is bound to the implemented candidate.",
         "Judge uses the approved acceptance scope.",
         "Iterate invalidates affected evidence after repair.",
-        "The coordinator aggregates seven-field final reports with phase-specific explanation."
+        "The coordinator aggregates five-section final reports with phase-specific explanation."
       ],
       "language": "en",
       "execution": "explain",