From de310a1b5540c727c580c5dcf62492a31a887f54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Mon, 27 Apr 2026 14:03:28 +0200 Subject: [PATCH 1/4] feat(instructions): Emphasize need for documentation in plan prior to proceeding to the next phase --- packages/core/src/instruction-generator.ts | 2 ++ packages/opencode-plugin/src/plugin.ts | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/core/src/instruction-generator.ts b/packages/core/src/instruction-generator.ts index c525b546..5c2bf023 100644 --- a/packages/core/src/instruction-generator.ts +++ b/packages/core/src/instruction-generator.ts @@ -115,6 +115,8 @@ export class InstructionGenerator implements IInstructionGenerator { **ACTION REQUIRED: Focus on "${phaseName}" tasks** and log decisions in "Key Decisions" +**When all tasks are completed**: Make sure that all insights and decisions are captured in \`${conversationContext.planFilePath}\`. Then call proceed_to_phase to move to the next phase. + **CRITICAL: Do NOT use other task/todo tools** - use only the plan file for task tracking`; // Add file restriction guidance if patterns are restricted diff --git a/packages/opencode-plugin/src/plugin.ts b/packages/opencode-plugin/src/plugin.ts index 900e325d..04c5f323 100644 --- a/packages/opencode-plugin/src/plugin.ts +++ b/packages/opencode-plugin/src/plugin.ts @@ -480,7 +480,7 @@ export const WorkflowsPlugin: Plugin = async ( Current phase "${state.phase}" only allows editing: ${allowedList} -ACTION REQUIRED: Use transition_phase tool to move to a phase that allows editing this file type, OR focus on files matching the allowed patterns above.`; +ACTION REQUIRED: Use proceed_to_phase tool to move to a phase that allows editing this file type, OR focus on files matching the allowed patterns above.`; logger.error('BLOCKING edit', { filePath, From 2e43cdc374afd2c5499f0e69f84f8ac04a1ad4d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Mon, 27 Apr 2026 14:05:43 +0200 Subject: [PATCH 2/4] feat(instructions): intent in epcc --- resources/workflows/epcc.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/resources/workflows/epcc.yaml b/resources/workflows/epcc.yaml index c172c0fb..88359449 100644 --- a/resources/workflows/epcc.yaml +++ b/resources/workflows/epcc.yaml @@ -31,6 +31,7 @@ states: - '**/*.txt' - '**/*.adoc' default_instructions: | + Figure out the INTENT of the users instructions. Research the codebase to understand existing patterns and gather context about the problem space. - If uncertain about conventions or rules, ask the user about them From 6b3ed265e2fdd3506157b3458fe541310c781f87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Mon, 27 Apr 2026 23:49:51 +0200 Subject: [PATCH 3/4] feat(workflows): first draft of a PR review workflow --- resources/workflows/pr-review.yaml | 177 +++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 resources/workflows/pr-review.yaml diff --git a/resources/workflows/pr-review.yaml b/resources/workflows/pr-review.yaml new file mode 100644 index 00000000..9f0df9c1 --- /dev/null +++ b/resources/workflows/pr-review.yaml @@ -0,0 +1,177 @@ +# yaml-language-server: $schema=../state-machine-schema.json +--- +name: 'pr-review' +description: 'A tech-agnostic PR or code diff review workflow: determine intent, review architecture, correctness, and quality — hierarchically gated, with findings posted inline.' +initial_state: 'determine_intent' + +metadata: + domain: 'code' + complexity: 'medium' + bestFor: + - 'Pull request reviews' + - 'Merge request reviews' + - 'Code review' + useCases: + - 'Reviewing a feature branch before merge' + - 'Reviewing a bug fix' + - 'Reviewing a refactoring' + examples: + - 'Review PR #42' + - 'Review the feature/login-refactor branch' + +states: + determine_intent: + description: 'Derive the intent of the PR from the diff and present it to the user for confirmation' + default_instructions: | + Fetch the diff (stat and full diff) for the PR or branch under review. + Retrieve the PR description and any linked issue descriptions. Use gh or glab CLI tools as needed. Fallback: Read using http. + + From the diff and any available PR description, derive in your own words: + - What problem does this change solve? What does the user intend to achieve? + - What is the mechanism used to solve it? + + Present your derived intent to the user and wait for explicit confirmation before proceeding. + If your derived intent contradicts the PR description or what the user responds to you, flag that explicitly — it is itself a finding. + + Respond in the user's language. + + transitions: + - trigger: 'intent_confirmed' + to: 'orient' + transition_reason: 'Intent confirmed by user, ready to map the change' + + orient: + description: 'Build a structural map of the change before any judgment' + default_instructions: | + Map the change without evaluating it yet: + - Which files changed, and what kind of change is each (new logic, refactor, configuration, tests, fixtures)? + - What are the entry points of the data or control flow affected by this change? + - Which existing boundaries or components does the change touch? + + Document this map. It will be the reference for all subsequent review phases. + + transitions: + - trigger: 'oriented' + to: 'review_architecture' + transition_reason: 'Structural map complete, ready to review architecture' + + review_architecture: + description: 'Review whether the change is in the right place and respects existing structure' + default_instructions: | + Evaluate the structural decisions in the change against the confirmed intent: + + - Is the change located in the right place, or does it belong elsewhere? + - Does it respect the existing boundaries and separation of responsibilities? + - Does it introduce the right abstraction, or does it over- or under-abstract? + - Does it follow the patterns already established in the codebase? + - If an architecture document exists ($ARCHITECTURE_DOC), verify the change is consistent with it. + + For each finding, classify it immediately: + - **Bug**: incorrect behavior or data loss + - **Design issue**: correct but wrong structure, will cause pain later + - **Performance**: correct but unnecessarily costly at the expected scale + - **Minor**: small violations, naming, unnecessary indirection + - **Nit**: style, redundant comments, cosmetics + + Bugs and design issues are major flaws. If major flaws are found, proceed to publish_review immediately. + + transitions: + - trigger: 'no_major_flaws' + to: 'review_correctness' + transition_reason: 'No major architectural flaws, proceeding to correctness review' + + - trigger: 'major_flaws_found' + to: 'publish_review' + additional_instructions: | + Major architectural flaws were found. Do not proceed to correctness or quality review — + reviewing correctness on a structurally wrong solution is wasted effort. + + Communicate clearly to the user: + - Which findings are blockers and why + - What rework is expected before the review can continue + transition_reason: 'Major architectural flaws found, stopping for rework before continuing' + + review_correctness: + description: 'Review whether the logic correctly achieves the confirmed intent' + default_instructions: | + Evaluate the logic of the change against the confirmed intent: + + - Does the code do what the intent requires, for all inputs and states? + - Are edge cases handled — boundary conditions, empty inputs, missing data? + - Are things that must stay consistent changed together? Can partial updates occur? + - Are error paths handled, or silently swallowed? + - Do resources that grow over time have a defined cleanup strategy? + - If a design document or specification exists ($DESIGN_DOC), verify the change is consistent with it. + + For each finding, classify it immediately (same scale as review_architecture). + + Bugs and design issues are major flaws. If major flaws are found, proceed to publish_review immediately. + + transitions: + - trigger: 'no_major_flaws' + to: 'review_quality' + transition_reason: 'No major correctness flaws, proceeding to quality review' + + - trigger: 'major_flaws_found' + to: 'publish_review' + additional_instructions: | + Major correctness flaws were found. Do not proceed to quality review — + polishing incorrect code is wasted effort. + + Communicate clearly to the user: + - Which findings are blockers and why + - What rework is expected before the review can continue + Proceed to publish_review to deliver these findings. + transition_reason: 'Major correctness flaws found, stopping for rework before continuing' + + review_quality: + description: 'Review code quality, completeness, and good practices' + default_instructions: | + Evaluate the quality of the change: + + - Is the code DRY, or is logic duplicated that should be shared? + - Does the code do unnecessary work — reimplementing what the platform already provides, + or repeating expensive operations that could be done once? + - Is naming self-explanatory at the right level of abstraction? + - Do comments explain *why*, not *what*? Are there comments that merely restate the code? + - Is what's absent a problem: missing tests, missing error handling, missing observability? + - Are there conventions in the codebase that this change violates? + + For each finding, classify it immediately (same scale as previous phases). + + transitions: + - trigger: 'quality_reviewed' + to: 'summarize' + transition_reason: 'Quality review complete, ready to summarize' + + summarize: + description: 'Compose a concise overall summary of the review' + default_instructions: | + Write a top-level review summary: + - Restate the confirmed intent in one sentence + - List blocking findings (bugs, design issues) if any remain + - List non-blocking suggestions briefly — the inline comments carry the detail + - State your overall recommendation: approve / request changes / comment + + Keep it short. The inline comments are the substance; this is the orientation. + + transitions: + - trigger: 'summary_ready' + to: 'publish_review' + transition_reason: 'Summary ready, proceed to publish' + + publish_review: + description: 'Ask the user how to deliver the review findings' + default_instructions: | + Ask the user how they want the review delivered: + - Post inline comments directly to the PR/MR via VCS tooling (e.g. glab, gh)? + - Present findings as a structured summary in the chat? + - Both? + + Once confirmed, deliver accordingly. For inline comments, attach each finding to the + specific file and line it refers to. For cross-cutting findings, use a top-level comment. + + transitions: + - trigger: 'review_published' + to: 'determine_intent' + transition_reason: 'Review delivered, ready for next PR' From 629432296bfc0b99102e771c765173325b7cd58c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oliver=20J=C3=A4gle?= Date: Tue, 28 Apr 2026 13:48:02 +0200 Subject: [PATCH 4/4] feat(posts): improve workflow with platform, emotional resonance and LinkedIn guidance - Story phase: decide primary platform early to influence narrative depth - Writing phase: add emotional resonance instruction and platform-specific formatting - Distribution phase: add concrete LinkedIn best practices (hook, takeaways, hashtags, cross-linking) Learnings from co-authored post with two perspectives on the same meeting. --- resources/workflows/posts.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/resources/workflows/posts.yaml b/resources/workflows/posts.yaml index 362e577a..15dceb59 100644 --- a/resources/workflows/posts.yaml +++ b/resources/workflows/posts.yaml @@ -53,6 +53,7 @@ states: - Create detailed story outline with clear beginning, middle, end - Identify key messages and memorable metaphors/examples - Define content scope boundaries to maintain focus and avoid adjacent topics + - Decide primary platform — it influences narrative depth and scope - Plan how content will adapt across different platforms - Ensure narrative arc matches chosen format (concise for short posts, comprehensive for long-form) - Structure content to maintain user's personal voice and conversational style @@ -89,6 +90,8 @@ states: - Write content following the established story outline - Maintain consistent narrative flow and personal voice + - Create emotional resonance: include moments where the author is uncertain, surprised or affected — readers connect through emotions, not just arguments + - Adapt formatting to primary platform (paragraph length, structure, takeaways) - Create engaging, conversational content in user's style - Ensure content length matches chosen format (3-10 lines for short, 2000-5000+ words for long) - Stay within defined content scope to avoid adjacent topics @@ -166,6 +169,7 @@ states: - Create compelling, SEO-optimized titles and descriptions - Add appropriate tags and metadata for discoverability - Adapt content formatting for different platforms (LinkedIn, Medium, HN) + - For LinkedIn: open with scroll-stopping hook, close with concrete takeaways, 3-5 targeted hashtags, cross-link co-authors - Maintain core message while adjusting for platform-specific requirements - Conduct final quality review and polish - Prepare publishing materials and schedule