feat(flow): refactor flow architecture, debloat skills, add project-local skills engine and hierarchical OKF - #70
Merged
Merged
Conversation
…ngine and hierarchical OKF - Refactor Flow lifecycle routing to direct Markdown frontmatter state synchronization - Consolidate all 12 auxiliary skills into single-file documents with OpenAI manifests - Add project-local tailored Flow skills scaffolding (.agents/skills/flow*) for zero-setup team portability - Add parallel fact-finding researcher agent and POSIX Git safety interceptor hook - Structure OKF bundles into hierarchical subdirectories (architecture, data-model, domains, decisions, rejections) - Debloat AGENTS.md, CLAUDE.md, and subagent prompts with affirmative operational language and zero em-dashes - Validate 100% test pass rate across 568 tests and multi-harness parity generators
The Claude PreToolUse hook now denies only Git operations it can literally recognize and allows everything it cannot classify, so variables, globs, pipes, redirections, quoted punctuation, and compound commands work again. The standalone installer handles CRLF sources, and the execution docs follow the journaled state contract. - Deny push, reset --hard, non-dry-run clean, tag mutation, tag fetching or pruning through options, config, or environment, forced branch deletion, and alias-based aliases; allow unknown subcommands and dynamic commands. - Close bypasses: bundled -D flags, --no-dry-run after -n, list-style tag options that do not imply --list, short and abbreviated tag fetch flags, case-insensitive git names, and .exe suffixes. - Keep hook cost linear so large commands classify well within the timeout. - Skip classification with a warning when jq is missing instead of blocking. - Preserve source line endings in the installer merge, hash content independent of line endings, honor umask for installed files, and adopt a byte-identical pre-existing copy instead of refusing it. - Route executor claim and close through journaled flow-state operations, drop the signed-commit requirement, restore complete and recover in the workflow template, and align finish guidance with the guardrail. - Skip POSIX-only fifo and socket cases on platforms without them.
Plain pushes go through the host's own permission prompt. The guardrail keeps denying force pushes, remote deletions, mirror and prune pushes, plus-refspecs, and any push that touches tags.
A marketplace-only Codex install can now perform the optional standalone project copy: the package generator renders the installer, the dependency graph, and every source the graph references, so the installer's default source root works from inside the package. - Derive the shipped sources from the graph instead of a hand-kept list. - Allow the new package entries in validation. - Prove the package yields the same standalone install as the repository for every supported host. - Point setup guidance at the package root as the installer's source root.
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.
Overview
This PR refactors the Flow architecture to streamline cognitive load, introduce project-local tailored Flow skills for zero-setup team portability upon
git clone, structure OKF bundles into hierarchical subdirectories, consolidate auxiliary skills into self-contained single-file manifests, and enforce direct Markdown frontmatter state synchronization.Key Changes
1. Direct Markdown Frontmatter State Synchronization
tasks/*.md->spec.mdchecklist markers:[ ],[~],[x] [<sha>],[!],[-])./flow:syncusing standard file tools.2. Project-Local Tailored Skills Engine (
.agents/skills/flow*)templates/agent/skills/(flow,flow-planning,flow-execution,flow-completion,flow-sync-status) allowing repositories to optionally include tailored Flow skills that auto-load for any developer cloning the repo without requiring global plugins.<!-- project-customization: start -->) to preserve project modifications across version syncs.3. Parallel Fact-Finding Research Swarm (
@researcher)@researchersubagent for/flow:researchto fan out background codebase investigations without blocking interactive planning.flow-reconcileragent in favor of direct file operations.4. Git Safety Interceptor Hook
hooks/block-dangerous-git.shand wiredPreToolUsefor Claude Code to block destructive Git operations (git reset --hard,git push -f,git clean -f, tag mutations).5. Hierarchical OKF Knowledge Bundles
.agents/bundles/into scope-derived subdirectories:knowledge/architecture/knowledge/data-model/knowledge/domains/knowledge/decisions/(1-paragraph ADRs)knowledge/rejections/(Rejection Memory catalog)archive/<year>/<flow_id>/(compact year-partitioned archiving)type,scope,domain,parent,supersedes,tags).6. Auxiliary Skills Consolidation
SKILL.mddocuments with standardizedagents/openai.yamlmanifests and required sections (## Workflow,## Guardrails,## Output,## Validation,## Example).references/directories across all 12 auxiliary skills.7. Linguistic Debloating & Standard Formatting
AGENTS.mdandCLAUDE.mdinto lean pointer files (<60 lines).—) across all framework documentation and enforced affirmative operational language.Verification & Testing
tools/validate.py): 0 violations across 20 skills, 18 commands, 24 agents.sync-agent-surfaces.py,sync-command-surfaces.py,sync-rule-surfaces.py,sync-manifests.py,sync-local-skill-templates.py, andaudit-skill-contracts.py.