feat: trim codebase, refactor abstractions, fix doc injection and project_path override - #293
Merged
Merged
Conversation
mrsimpson
force-pushed
the
feat/feature-inventory
branch
from
September 21, 2026 08:42
50fd710 to
3713535
Compare
## Intent The package had accumulated dead features — beads, commit plugin, plugin system, MCP resource registry, artifact-check, branch-prompt, crowd workflows, visualization CLI — that were no longer used but still tested and maintained. Carrying them increased the surface area for bugs, slowed down comprehension, and made the test suite harder to trust. Removing them and collapsing the abstractions they left behind brings the codebase down to what is actually needed. ## Key decisions - Deleted packages/visualizer and original packages/docs rather than leaving them dormant — they had no consumers and would have needed ongoing maintenance. - Collapsed IPlanManager, IInstructionGenerator, ITaskBackendClient: each had exactly one implementation; the interfaces added indirection with no benefit. - Replaced five ad-hoc test-access methods with a single handleTool<T> generic to reduce test boilerplate without losing type safety. - Kept all domain filtering (WORKFLOW_DOMAINS, metadata.domain) — it is used by non-code workflow variants and removing it would be a behaviour change. ## Side effects - 3 crowd YAMLs deleted (sdd-feature-crowd, sdd-bugfix-crowd, sdd-greenfield-crowd) - registerMcpResources, ResourceRegistry, setTaskBackend, setStateMachine, GitCommitConfig, shadow ConversationContext, role?/collaboration/requiredRoles removed from state machine types - SessionMetadata deduplicated; ConversationStateReader interface extracted - 35 previously disabled test files re-enabled; tests for deleted modules deleted - Stray smoke-test scripts and conversation state files removed from tracked tree; mcp-call*.mjs and scripts/disable-tests.js added to .gitignore
## Intent Workflows that reference project documents need to tell the agent to read those files, but only when they actually exist. Previously this was done with $ARCHITECTURE_DOC variables hardcoded into instruction text, which produced literal file paths regardless of whether the file existed, and with conditional fallback prose duplicated across many YAMLs. A declarative referred_docs field on phases replaces both: the server injects a read instruction at runtime only when the file is present. The docs package is restored so the visualizer is accessible again. The requiresDocumentation artifact check is also restored after being incorrectly removed during the trim. ## Key decisions - referred_docs is phase-level ([requirements|architecture|design]) rather than workflow-level, because different phases care about different documents. - File existence is checked at runtime in injectReferredDocs() so a missing file silently skips the sentence instead of failing the tool call. - $ARCHITECTURE_DOC etc. in YAML body still substitute to literal paths via getVariableSubstitutions() for cases where the path is needed as an output target; the conditional path is only used for referred_docs injection. - WorkflowVisualizer inlined as a single SFC into packages/docs rather than keeping a separate packages/visualizer package — one fewer build artifact. - All $*_DOC references removed from phase instruction text in 13 workflow YAMLs and replaced with plain behavioural instructions so they remain valid whether or not the doc exists. ## Side effects - 11 of 22 workflow YAMLs updated with referred_docs; old "If $X exists:" sentences removed - 13 YAMLs had $*_DOC instruction text replaced with plain instructions - instructionSource: 'plugin_hook' added to suppress whats_next() reminder in opencode context - start-development-artifact-detection.test.ts restored (8 tests) - MockContextFactory.createBasicContext updated with generateWorkflowDocumentationUrl mock - instruction-generator-referred-docs.test.ts added with regression suite
## Intent The docs package and its companion visualizer package were deleted early in the trim. Restoring them makes the workflow visualizer accessible again without requiring a separate npm package. Inlining the visualizer as a self-contained Vue SFC into the docs VitePress site removes the packages/visualizer build artifact entirely while keeping the feature available at the docs URL. ## Key decisions - WorkflowVisualizer inlined as a single SFC (~650 LOC) in packages/docs/.vitepress/ rather than keeping a separate packages/visualizer package — one fewer package to build, version, and publish. - Deleted stale docs pages for removed features: beads-integration, crowd-mcp-integration, git-commit-feature, long-term-memory (beads), dev/ directory. - packages/docs/public/workflows/ excluded from git — the prebuild script copies from resources/workflows/ at build time so committing them is redundant. ## Side effects - packages/visualizer deleted (22 files) - packages/docs restored with updated content: WorkflowVisualizer.vue, workflow-manifest.js, visualizer.md page, updated nav/sidebar in config.ts - turbo.json updated to add .vitepress/dist/** to docs build outputs - docs:build and docs:dev scripts added to root package.json
## Intent whats_next, proceed_to_phase, conduct_review, resume_workflow, and reset_development all accepted a project_path argument in their schemas but silently ignored it, always resolving the conversation via the server's PROJECT_PATH env var. This made it impossible to use those tools against a project other than the one the server was started for — the parameter appeared to work but had no effect. ## Key decisions - Added a getProjectPathOverride(args) hook on ConversationRequiredToolHandler that returns undefined by default; handlers that accept project_path override it. This keeps the base class generic without requiring every handler to know about project paths. - ConversationManager.getConversationContext() now accepts an optional projectPathOverride, consistent with the pattern already used by initializeConversation(). ## Side effects - project_path added to Zod schemas for all five affected tool registrations - resetConversation() in ConversationManager updated with the same override pattern
## Intent Three crowd workflow variants (sdd-feature-crowd, sdd-bugfix-crowd, sdd-greenfield-crowd) were removed as part of the trim. They were left unstaged during the refactor commit by accident — moving them into the refactor commit would require a rebase, so this finalizes their deletion cleanly. ## Side effects - resources/workflows/sdd-bugfix-crowd.yaml deleted - resources/workflows/sdd-feature-crowd.yaml deleted - resources/workflows/sdd-greenfield-crowd.yaml deleted
mrsimpson
force-pushed
the
feat/feature-inventory
branch
from
September 21, 2026 09:21
3713535 to
dfe8d33
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Trimmed
@codemcp/workflowsfrom ~14,900 to ~10,900 LOC by removing dead features, then refactored the remaining codebase and fixed two bugs.Changes
Dead code removal
packages/visualizerand the originalpackages/docssdd-feature-crowd,sdd-bugfix-crowd,sdd-greenfield-crowd)Refactoring
IPlanManager,IInstructionGenerator,ITaskBackendClient)registerMcpResources/ResourceRegistry,setTaskBackend,setStateMachine,GitCommitConfig, shadowConversationContext,role?/collaboration/requiredRolesfrom state machine typesSessionMetadata, extractedConversationStateReaderinterface, replaced 5 test-access methods withhandleTool<T>genericNew feature:
referred_docsreferred_docs: [requirements|architecture|design]InstructionGenerator.injectReferredDocs()checks file existence at runtime and prepends contextual read instructionsreferred_docs; old conditionalexists:sentences removedBug fix:
project_pathoverridewhats_next,proceed_to_phase,conduct_review,resume_workflow,reset_developmentnow useproject_patharg to override the server'sPROJECT_PATHenv vargetProjectPathOverride(args)hook onConversationRequiredToolHandlerDocs restored
packages/docsrecreated as VitePress site withWorkflowVisualizer.vueinlined as a single SFC (~650 LOC)Tested
pnpm build: zero errorspnpm test: 699 passing, 0 failingproject_pathoverride verified via end-to-end smoke test