royascaff v1.2.5 · MIT · works in Cursor

The plan and the code are
the same artifact.

RoyaScaff is a control engine for building software with AI. It drives the model from a product description through planning, action specs, code generation and verification — and rewrites the blueprint every single time the code changes.

$ npx royascaff init
Star on GitHub
  • MIT licensed
  • No lock-in, no runtime
  • Any stack, any repo
Hands drafting a technical drawing with a ruler and pencil
Before the build, the drawing.

The whole idea

A change lands in both places, or it hasn't landed.

Pick a change below. The spec moves on the left, the code moves on the right, and the work pack walks its status until main is updated. Nothing is written to the blueprint before verification passes.

project/changes/change-20260804-142310-coupon-code/

project/actions/orders/endpoints.md Plan 

        


        

        

          

            
            src/api/orders/checkout.ts
            Code
          

          

        

      


      
    
        
  1.  drafted
    2. 
        
  2.  in-progress
    3. 
        
  3.  verified
    4. 
        
  4.  merged
    5. 
      

    


    

      Main is the implemented reality. In-flight work never touches it — it lives in the pack until
      verify-code.md comes back PASS.
    

  







  

    

      
 Why this exists

      
AI writes code fast. Then it forgets.

      

        The first session is magic. The trouble starts at the second feature, when the model has no
        idea what the first one promised.
      

    


    

      

        
        
The plan rots after session one

        

          You start from a clear description. Ten prompts later the code has moved and nothing wrote
          it down. The document you are still reading is now fiction.
        

      

      

        
        
The second feature breaks the first

        

          With no data model, service list or endpoint contract to check against, every addition is
          a guess about what already exists — and guesses collide.
        

      

      

        
        
Nobody can rebuild the reasoning

        

          A new developer, or a new chat window, reads the code and gets the what. The
          roles, the rules, the shape of the thing, the why: gone.
        

      

    


    

      

        Lines of source code on a dark screen
      

      

        
Control is not the same as autocomplete.

        

          RoyaScaff does not make the model faster. It makes the model accountable.
          Every artifact it produces has a place to live, a status, and a verification step before
          it is allowed to become the truth.
        

        

          Not “generate an app and hope” — a controlled path from product description to plan to
          action specs to code to verify.
        

      

    

  







  

    

      
 The control path

      
Nothing gets written before it gets specified.

      

        Five stages, always in the same order. The engine refuses to skip ahead, which is exactly
        what makes the output reviewable.
      

    


    
    
      
  1. 
        01
        
        
    Description
    
        
    What the system is, who uses it, what it must do. Not a prompt — a document.
    
      
    2. 
      
  2. 
        02
        
        
    Plan
    
        
    Modules, data model, roles and authorization, business rules. Agreed before any code.
    
      
    3. 
      
  3. 
        03
        
        
    Action specs
    
        
    Services, endpoints, pages and views — written per module, in dependency order.
    
      
    4. 
      
  4. 
        04
        
        
    Code
    
        
    Generated against the spec, inside an isolated work pack, never straight onto main.
    
      
    5. 
      
  5. 
        05
        
        
    Verify
    
        
    Checked against the spec it came from. PASS is what unlocks the merge back to main.
    
      
    6. 
    


    

      
Traceability chain

      

        Data Model
        
        Services
        
        Endpoints
        
        Pages / Views
      

      

        Generation runs left to right. Dependencies run right to left: pages depend on endpoints,
        endpoints on services, services on repositories. Break one link and the engine tells you
        which spec is missing instead of inventing it.
      

    

  







  

    

      
 The blueprint

      
One folder that holds the whole system.

      

        project/ is not shipped with the engine — it is generated for
        your system, and from then on it is the map everyone reads, humans and models alike.
      

    


    

      

        
project/
├── profile.md            stack, brand, paths — the only system-specific file
├── description.md        what this system is and who it serves
├── plan/
│   ├── modules.md        the shape of the system
│   ├── data-model.md     entities, fields, relations
│   └── roles-and-authorization.md
├── actions/<app>/       services, endpoints, pages, views
├── rules.md              business rules that outlive any one feature
├── status.md             done · partial · planned · deferred
├── changes/
│   ├── change-log.md     live index of every work pack
│   ├── build-program.md  ordered queue of build packs
│   └── change-<ID>-<slug>/ in-flight work, isolated
└── bugs/bug-log.md      PENDING · DONE · ESCALATED

      


      
    


    

      
      

        
The rebuild test

        

          Copy project/ on its own to an empty machine. It must be enough
          to rebuild the implemented app. If it isn't, the blueprint has drifted — and that counts
          as a bug, not a documentation chore.
        

      

    

  







  

    

      
 Change isolation

      
Work packs, not one giant risky session.

      

        Every implementation — greenfield or feature or bug — runs inside its own pack. Specs are
        drafted there, code is written there, verification happens there. Main is updated once, at
        merge.
      

    


    

      

        
project/changes/change-20260804-142310-coupon-code/

        
change-request.md   what is being asked for
impact.md           what this touches, and what it doesn't
status.md           pack-status, artifacts done / total
blueprint/          the delta specs, in-flight only
verify-code.md      PASS is the gate to merge
merge-report.md     written after main is updated

      


      
    
        
  • drafted Folder and request created. No code yet.
    • 
        
  • in-progress Implementation started against the delta spec.
    • 
        
  • verified Verification came back PASS overall.
    • 
        
  • merged Main blueprint now reflects the new reality.
    • 
        
  • cancelled Abandoned. Main was never touched.
    • 
        
  • blocked Waiting on a pack it depends on.
    • 
      

    


    

      

        
 IDs are datetimes, not counters

        

          A pack is 20260804-142310, not #7.
          Two developers on two branches can both open a pack this afternoon and merge without
          collision.
        

      

      

        
 Small packs, parallel work

        

          Greenfield is not one monolithic build — it's a queue of build packs in
          build-program.md. Stop any time; resume from the change log.
        

      

    

  







  

    

      
 Five ways in

      
Open flow.md. Pick the flow that matches the job.

      

        One router file decides everything. You say what you're doing; it loads the right workflow
        and the right templates.
      

    


    

      

        
Phase 0–4

        
/initial-build

        
Greenfield. Design on main, then implement through ordered build packs — never one giant generate.

      

      

        
Phase 5

        
/change-mode

        
A new or changed capability: fields, endpoints, pages with behavior. Fast-track for small ones, full flow for the rest.

      

      

        
Phase P

        
/polish

        
Style, spacing, copy, the way a button looks. Explicitly nothing that touches behavior.

      

      

        
Phase 6

        
/bug-fix

        
Something behaves differently from the documented expectation. Logged, fixed, and checked against the spec.

      

      

        
Phase R

        
/reverse-engineer

        
You inherited an undocumented codebase. Document what's there on main, then close the gaps with packs.

      

      

        
Already have a repo?

        
Start with reverse-engineer. You get a blueprint of what you actually own before you change a line of it.

        Get started 
      

    

  







  

    

      
 Install

      
One command. No configuration.

      

        It copies the engine and the skills into your project. It does not create the blueprint —
        the engine writes that when you start your first flow.
      

    


    

      

        

          
          
          
        


        

          

            $
            npx royascaff init
            
          

          
Scaffolds the engine into the current project root.

        


        

          

            $
            npx royascaff init --git
            
          

          
Initializes git inside royascaff/ only — your project keeps its own history.

        


        

          

            $
            npx royascaff init ./my-app --git
            
          

          
Point it anywhere. Add --force to overwrite an existing scaffold.

        

      


      

        
what lands in your repo

        
your-app/
├── .cursor/skills/   /flow, /initial-build, /change-mode …
├── royascaff/engine/ flows, templates, rules
└── project/          generated later, by the engine

      

    


    
    
      
  1. 1Open royascaff/engine/flow.md.
    2. 
      
  2. 2Tell it what you're doing — new build, feature, polish, bug, or inherited code.
    3. 
      
  3. 3Review each artifact as it appears. You approve; the model executes.
    4. 
    

  







  

    

      A team of developers working together around laptops
    

    

      
 In practice

      
Built by a team that ships with it every day.

      

        RoyaScaff came out of real sessions: two developers, one control flow, a product going out
        the door. The rules in it are the ones that survived contact with actual deadlines.
      

      

        If your AI workflow already feels shaky at feature two, this is the part that fixes it —
        and it costs one command to find out.
      

      

         Try the engine
         Ask a question
      

    

  







  

    

      

        
 Contribute

        
MIT. Fork it, change it, ship it.

        

          Use it commercially, modify it, build products on top of it. The engine is plain markdown —
          flows, templates and rules — so improving it means writing better instructions, not
          learning a framework.
        

        

          Better flows, sharper templates and clearer rules help everyone building this way. Open a
          pull request.
        

        

          
             roya-tech-team/royascaffold
          
          
             npm package
          
        

      


      

        
 Contact

        
Tell me what you're building.

        

          Want help wiring RoyaScaff into your team's workflow, or have an idea for the engine?
          Write to me directly — I read every message.
        

        
          
          islam@roya.marketing