nop-chaos-flux is a low-code runtime framework built on React 19, Zustand 5, and Vite 8. It is inspired by Baidu AMIS but independently implemented from scratch based on innovative design principles. It includes a JSON Schema compiler and runtime, as well as design tools such as a report designer and Flow Designer.
The initial version of this project was completed by a single programmer in two months, developed entirely through AI automation. Unlike typical AI-assisted development, as features were continuously added, the project did not suffer from quality degradation. Instead, module boundaries became clearer, document categorization more stable, testing and auditing increasingly captured real issues, and code quality continuously improved.
I recently gave some internal sharing sessions and named this practice Attractor-Guided Engineering (AGE). Later, during code reviews, I found that many people did not truly understand it. Some operated in a way close to casual vibe coding, while others adopted a spec-driven development style similar to OpenSpec, leaning overall toward task-driven, feature-by-feature development. As the workload accumulated, inconsistencies in the code steadily built up, and deviations from the architectural design became the norm.
This article analyzes the differences between AGE and spec-driven development, and what ordinary business projects can learn from the large-scale AI engineering practices of nop-chaos-flux.
Core Hierarchy
At the heart of AGE lies the following conceptual hierarchy:
State Space → Attractor → Trajectory → Control
- State Space: All possible implementation states the system can evolve into under current constraints.
- Attractor: The stable structure to which the system is repeatedly pulled back during long-term evolution.
- Trajectory: The actual evolutionary path preserved after each round of generation, verification, and correction.
- Control: Various mechanisms that continuously influence the trajectory through local signals.
All possible combinations of code, documentation, and tests that the repository could evolve into under existing constraints constitute the state space. The continuous actions of humans, AI, review, CI, and document updates form the evolutionary rules. The live repo history created by the superposition of the two is the trajectory. The attractor is the stable structure to which the system is repeatedly pulled back over long-term iteration.
Large-scale AI development is essentially a controlled convergence problem for a dynamical system. AI expands the state space extremely fast. The key is not to add guardrails everywhere, but to first figure out: what structure should the system be pulled back to over the long term?
An attractor is not a fully written-out end point, not a roadmap, and not a "scope of permitted activity." It is a structure implicitly defined by a small set of high-order constraints: local implementations can vary, but the whole will be pulled back to the same type of form by these relationships.
In nop-chaos-flux, what first defines the attractor is not the plan, lint, test, audit, or any single spec file, but the architecture docs with precedence under docs/architecture/. In the following text, these architecture docs with owner and precedence are referred to as owner docs.
docs/architecture/README.md explicitly states: docs/architecture/ is the current final-state architecture baseline, flux-design-principles.md is the governing-principles anchor, frontend-programming-model.md holds the top-level primitives and core-boundary precedence, and other normative docs hold local precedence within their respective topics.
These documents do not enumerate all correct implementations. They define a stable structure like an equation: what primitives exist, which dependency directions are legal, which owner boundaries must not be broken, and which old patterns no longer belong to the correct state space. They first define the cluster of states that can sustainably exist, so that subsequent implementation, testing, planning, and auditing have a reference.
Plan, verification, audit, logs, bugs, testing all come later. They are not the attractor itself, but the harness that keeps the system trajectory continuously close to the attractor.
Flux/AGE is not centered on spec evolution, but on attractor definition and trajectory convergence.
Real Development History
"Architecture docs define the attractor" might sound like ordinary document governance at first, but the difference becomes clear if you carefully examine the actual development records in docs/logs/.
For example, docs/plans/371-deep-audit-2026-05-19-owner-routing-plan.md is a typical entry point. It does not directly change the code, but converges the 64 retained findings from the 2026-05-19 deep audit into an owner-routing baseline. Each finding has a unique owner bucket, priority, successor plan, and owner-doc obligation. No ownerless items, no multiply-owned items, no silent downgrade to vague follow-ups.
Its role is to first freeze how a round of deviations should be resolved, after which the subsequent execution plans close the local trajectory to concrete outcomes. docs/plans/382-deep-audit-2026-05-19-table-and-crud-owner-state-and-event-contract-plan.md resolves the table/CRUD owner state and event payload: Current Baseline declares the live status of explicit empty-array owner state and event payload, execution items fix the empty-array fallback, focused tests prove the result, docs/components/table/design.md and docs/components/crud/design.md synchronize the owner contract, and finally repo-wide pnpm typecheck, pnpm build, pnpm lint, pnpm test all pass, with the independent closure audit ses_1bd9ed593ffeVpkho4lb4wPR6p recording Verdict: acceptable.
docs/plans/388-deep-audit-2026-05-19-form-tree-widget-accessibility-plan.md demonstrates another type of closure: visible node roving focus, ArrowUp/ArrowDown/Home/End navigation, loading aria-busy/aria-describedby for input-tree and tree-select all have focused proof, but the plan explicitly rules No owner-doc update required. This shows that a plan is not just a to-do list; it is also responsible for judging whether this change modifies the owner-doc baseline.
docs/plans/400-deep-audit-2026-05-19-test-harness-reliability-plan.md and docs/bugs/62-e2e-shared-websocket-error-suppression-fix.md demonstrate the role of memory harness. The problem was not a business function failure, but that the E2E shared fixture's filter scope was too broad, filtering out real transport/runtime failures as well. The fix not only changes the code, but also adds tests/e2e/fixtures-hard-gate.spec.ts to prove it now fails, and records a rule in the bug note: if future tests genuinely expect a WebSocket failure, a per-test allowance must be used, and fixture-wide suppression must not be restored.
docs/logs/2026/05-19.md and docs/logs/2026/05-20.md are not mere daily logs. They record the focused proof of each closure slice, owner-doc rulings, repo-wide gates, independent audits, and full-green baselines.
These materials form a real chain: owner docs define the long-term structure, audits discover deviations, plans route and freeze ownership, focused proof demonstrates local results, owner-doc rulings decide whether to update, logs/bugs/testing preserve cross-session memory, and closure audits re-judge completion status from the live repo.
This is the harness in AGE. The goal is not to make each task appear more complete, but to make the system trajectory continuously return to the vicinity of the attractor.
Where OpenSpec's Structure Excels
OpenSpec is a representative spec-driven development framework that structures a category of work well:
-
openspec/specs/stores the behavioral specifications of current capabilities. -
openspec/changes/stores proposed changes, includingproposal.md(why change, what changes, impact),design.md(technical design when necessary), andtasks.md(implementation checklist). -
changes/<name>/specs/records spec deltas usingADDED/MODIFIED/REMOVED/RENAMED. - Archive applies the deltas back to the main specs through fixed rules.
This mechanism lowers the cost of updating specifications. OpenSpec does not require the AI to freely understand the entire requirement and then arbitrarily modify documents each time. Instead, it uses fixed sections, requirement header matching, and delta application to merge structured changes back into the main specs. This approach is well-suited for scenarios where behavioral specifications are clear and need to be parseable, archivable, and re-writable.
Where OpenSpec Is Limited
OpenSpec's spec format (Requirement, Scenario, SHALL/MUST, delta sections) is tool-parseable friendly, but is not flexible enough as a way to organize general project knowledge.
A lot of repository knowledge does not naturally grow into requirement/scenario form:
- Architecture hierarchy and precedence.
- History of terminology misunderstandings.
- External research materials (PPT, discussion records).
- Analysis conclusions from a source code audit.
- Phenomena discovered through manual testing.
- The elimination path of a complex bug.
- Why a plan cannot be closed.
If everything must first be translated into a spec/change to gain an official place, the conversion cost is high, and the original context is also lost. External documents, discussion records, analysis reports, and bug retrospectives could directly become repository memory. Forcing them into requirement/scenario format tends to flatten the information.
In terms of execution verification, the two reflect different tool philosophies. OpenSpec's tasks.md is a checklist; /opsx:verify is an optional agent verification skill (requires manually enabling expanded workflows). archive checks task status and prompts about risks, but can still proceed after user confirmation—strict closure is left to the team's own conventions.
Flux plan, on the other hand, bakes independent closure audit in as a required step: you must start from the current baseline, write clear Goals, Non-Goals, execution items (each annotated with Fix/Decision/Proof), and Closure Gates; before marking completed, an independent sub-agent or independent reviewer must go back to the live repo and perform a closure audit. docs/plans/361-slot-contract-host-manifest-and-owner-doc-closure-plan.md puts together the current baseline, the finding ownership matrix, execution phases, closure gates, the deferred items that have been ruled on, and independent review evidence. This is not a checklist, but an execution contract that strictly defines closure conditions and requires independent audit. It emphasizes not what was done, but to what standard something counts as truly landed.
Why Spec-Driven Easily Becomes Task-Oriented
The default structure of spec-driven development easily pulls the attention of both humans and AI back to "how to complete this change."
A change typically has a proposal, design, tasks, and delta specs. This is much better than verbal requirements, but it is naturally organized around one change: why change, what to change, how to do it, which checklist items are done. Over time, spec-driven development can easily become a more formal task dispatch system.
This task orientation has a hidden risk: specs are updated, tasks are checked, archive is done, and both AI and humans get a strong sense of completion. But whether the system is truly closer to the long-term structure is not proven by the change itself. It must be verified by looking back at the architecture docs, the live repo, tests, logs, and independent audits.
If one tries to long-term maintain specs to the level of precision in Flux, the cost is usually higher. What Flux maintains is not a single specification tree, but a set of repository memories with different responsibilities: architecture docs define the attractor, plans define local trajectory closure, logs record evolution, bugs preserve complex defect diagnosis, testing preserves manual findings, analysis preserves research judgments, and audit is responsible for looking back at the live repo. Cramming all of this into a spec/change structure incurs continuous conversion cost.
Spec-driven can serve as a local harness within AGE to manage behavioral spec evolution. But it should not replace architecture docs, nor should it replace the separate repository memories of plan closure, logs, bugs, testing, and audit.
What If You Just Need to Look Up an Owner Doc?
This reveals a fundamental difference between the two approaches.
If, in Flux, you simply want to check the current owner contract of the renderer runtime, you can directly route from docs/index.md to docs/architecture/renderer-runtime.md and the relevant references. You do not need to create a change, do not need a proposal, do not need tasks, and do not need to rewrite the question into a spec delta.
If it's just research, it might go into docs/analysis/. If it's just a discovery from manual testing, it goes into docs/testing/ first. If it's a complex bug, it goes into docs/bugs/. If it's an execution closure, then a plan is written. A stable baseline change then goes back to the owner doc.
Flux's document organization is free but not arbitrary. Free means: it does not force all knowledge to first enter the same artifact workflow. Constraint means: each type of material has a clear responsibility and cannot arbitrarily compete for factual status.
OpenSpec's organization is more structured. It is good at putting proposed behavioral changes into a change package and then writing spec deltas back to main specs. But general repository knowledge routing is not the main problem it aims to solve by default.
Tasks Are Not Plans
OpenSpec's tasks.md does not correspond to Flux's plans.
tasks.md at most corresponds to the execution checklist fragment inside a Flux plan, or the todo list of the current session. It can help AI avoid missing steps, but it does not answer these questions:
- What is the current live repo baseline?
- What is explicitly not being done this time?
- What evidence can prove it is truly complete?
- Which defects cannot be downgraded to follow-ups?
- Who independently verifies the completion status?
The value of a Flux plan is not in "having more tasks," but in it being a closure contract for a local trajectory.
So tasks are necessary for AI, but tasks are not the source of truth. - [x] only indicates that the executor claims an item is complete. The real proof must return to the current code, tests, owner docs, and independent review.
Sources of Change Go Beyond Spec Changes
OpenSpec's path is very clear: organize behavioral spec evolution around specs and changes.
Flux's sources of change are broader:
- New requirements raised by users.
- Architectural drift discovered by reading source code.
- Owner boundary problems discovered by audits.
- Interaction problems exposed by testing issues.
- Historical regression risks recorded in bug notes.
- Design judgments derived from external research or analysis.
- A plan closure audit overturning a previous judgment of "completed."
These sources should not all be transformed into spec deltas first. They can first land in analysis, testing, bugs, logs, plans, or directly update architecture docs. Whether they ultimately need to become a behavioral contract depends on whether they are part of the long-term baseline.
This is the significance of Flux's organizational freedom in documentation. Information from different sources first stops at different positions, rather than being shoved entirely into a single spec evolution channel.
Why Files-In, Files-Out Matters
I have emphasized many times in sharing sessions that a best practice for AI-driven development is files-in, files-out. This is not just documentation fastidiousness—the attractor and the harness need a physical carrier.
Files-in: do not leave input only in the chat window. Even if the content is messy, first write it to a requirements file, analysis file, or plan file, and then @ this file in OpenCode.
Files-out: do not end with output just printed in the window. Important conclusions, analyses, plans, test records, bug diagnoses, and architectural constraints are all written into docs/, categorized by responsibility:
- Architecture rules →
docs/architecture/ - Change closures →
docs/plans/ - Execution trajectory →
docs/logs/ - Manual testing findings →
docs/testing/ - Complex defect diagnosis →
docs/bugs/ - Research judgments →
docs/analysis/
The point is not "write more documents." Once output is categorized and persisted, it enters the repository memory. The chat window is temporary context; files are the repository memory.
Code Is the Current Implementation Fact, Not the Only Fact
Code is the source of truth for the current implementation. Types and tests protect the current behavior. The architecture owner docs with precedence define the attractor—the structure the system should converge to over the long term. Logs, bugs, analysis, and testing record the trajectory and externalize memory.
These do not conflict. Conflicts arise in two situations:
- When documents start regurgitating implementation details that easily rot.
- When the completed state of a document is taken as proof that the code is already correct.
OpenSpec's behavior-first boundary actually avoids the first problem to some extent: behavioral specs should write verifiable behavior, not internal implementation details. Flux further emphasizes the second problem: even if the document describes the correct behavior, it cannot replace the verification of the current repository. True closure must return to code, tests, owner docs, logs, and audit evidence.
The Real Difference
What OpenSpec solves: how to use structured specs/changes/delta/archive to organize the update of behavioral specifications, focusing on the evolution flow of specs.
What AGE solves: when AI rapidly expands the state space, how the system first defines an attractor, and then uses harnesses such as plan, verification, audit, logs, bugs, analysis, and testing to make the trajectory continuously converge.
The two tools solve problems at different levels. OpenSpec's strength is the structured specification workflow. Flux/AGE's strength is using architecture owner docs with precedence to define the attractor, and then using free but responsibility-bounded document routing and a strict closure harness to make the repository converge over the long term.
Moving from spec-driven development to Attractor-Guided Engineering is not moving from "writing specs" back to "not writing specs," but moving from "organizing changes into spec updates" toward "defining where the system should converge over the long term, and making every round of AI generation continuously pulled back by this structure."
What Ordinary Projects Can Directly Adopt
There is no need to copy the full governance of Flux.
First, files-in, files-out. Write input into a file first before @-ing it to AI; output goes into docs/, not left only in the chat window. This step takes just a few minutes, but it gives AI traceable repository memory instead of relying on conversational context.
Second, write an architecture document for the core business that defines the business attractor. Do not write a code guide. Instead, write down the sources of truth, state transitions, ownership boundaries, and common misunderstandings.
Third, write lightweight plans for complex changes. Include the current baseline, goals, what is not being done, an execution checklist, proof items, and closure conditions. Before completion, have an independent session or independent reviewer re-verify.
Fourth, turn recurring problems into repository memory. Manual issues go into testing, complex bugs go into bugs, research conclusions go into analysis, and high-frequency errors go into audit scripts.
Specification updates are a necessary layer. System convergence still needs an attractor.
nop-chaos-flux is open source:
Top comments (0)