Getting Started with Noderr: A Complete Guide

August 16, 2025 · View on GitHub

Welcome to Noderr!

Noderr is a systematic development methodology that transforms your AI assistant from a chaotic coder into a disciplined, professional software engineer. It uses a structured loop and a library of prompts to build software that is well-documented, properly tested, and robust enough for long-term maintenance.

Why Noderr? Without structure, every AI-driven project risks the same fate: initial rapid progress followed by unmanageable complexity, outdated documentation, and eventual abandonment. Noderr prevents this by instilling professional software engineering practices into the AI's workflow from day one.

Table of Contents

  1. Quick Start
  2. Installation
  3. Initial Setup Process
  4. The Noderr Loop
  5. Daily Workflow
  6. Specialized Workflows
  7. Command Reference
  8. Troubleshooting
  9. Best Practices

Quick Start: Your First Project with Noderr

Overview of the Process

Unlike traditional setups, Noderr has a unique workflow:

  1. Prepare your project vision (3 key files)
  2. Build an initial prototype with AI
  3. Install Noderr to manage the project going forward
  4. Develop systematically using the Noderr loop

This approach ensures Noderr documents what you ACTUALLY built, not just what you planned.

Installation

Download Noderr

  1. Download the latest release: noderr.starter.zip
  2. Keep the ZIP file handy - you'll extract it AFTER your initial build

The ZIP contains:

your-project/
└── noderr/                    # Everything inside!
    ├── noderr_project.md
    ├── noderr_architecture.md
    ├── noderr_tracker.md
    ├── noderr_log.md
    ├── noderr_loop.md
    ├── environment_context.md
    ├── specs/
    ├── planning/
    └── prompts/

Initial Setup Process

Step 1: Prepare Your Vision (Before Any Coding)

You need to create three foundational documents. There are many ways to approach this - through conversation with your AI, using specific prompts, or a combination. Here's one structured approach:

Option A: Structured Design Strategy Approach

  1. Blueprint/Design Document (using a Design Strategy prompt)

    • One effective method is using a UI/UX Design Strategy System prompt
    • This generates Design Pillars → Implementation Tasks → Visual Blueprint
    • Provides comprehensive strategic foundation for your project

  2. Project Overview (noderr/noderr_project.md)

    • Can use noderr/prompts/NDv1.9__Project_Generator.md prompt (if available)
    • Or create through conversation based on your blueprint
    • Defines technology stack, standards, and scope

  3. Architecture Diagram (noderr/noderr_architecture.md)

    • Can use noderr/prompts/NDv1.9__Architecture_Generator.md prompt (if available)
    • Or design through discussion using your blueprint as reference
    • Creates the technical system design

Option B: Conversational Approach

Simply have an extended conversation with your AI about:

  • What you want to build
  • Who will use it
  • Core features and functionality
  • Technical preferences
  • System design

Option C: Hybrid Approach

Mix prompts and conversation:

  • Start with a structured prompt for initial ideas
  • Refine through conversation
  • Use specific prompts for technical details

Pro tip: Create all three documents in the same chat session, allowing each to inform and refine the others. The key is having clear, comprehensive plans before any code is written.

Step 2: Build Your Initial Prototype

  1. Give all three documents to your AI

    "Here are my project plans: [paste the 3 documents]
Please build the initial version of this application."

  2. Let the AI build the first version

    • It will create the basic structure
    • Implement core features
    • Set up the project

  3. Test and verify the initial build works

Step 3: Install Noderr (After Initial Build)

NOW extract the Noderr ZIP into your project root:

# Extract the ZIP
unzip noderr.starter.zip -d your-project/

# You should see:
your-project/
├── your-code-files...        (already built)
└── noderr/                   (just extracted)
    ├── noderr/environment_context.md
    ├── noderr/noderr_project.md
    └── ... other Noderr files

Step 4: Run Install and Reconcile

Give your AI this command:

noderr/prompts/NDv1.9__Install_And_Reconcile.md

Step 5: Verify System Readiness

After installation, run a comprehensive audit:

noderr/prompts/NDv1.9__Post_Installation_Audit.md

This will:

  • Verify all Noderr components are working
  • Identify missing architectural NodeIDs
  • Auto-create specifications for gaps
  • Provide development readiness report

Step 6: Begin Systematic Development

Once audit shows 100% readiness:

noderr/prompts/NDv1.9__Start_Work_Session.md

You're now ready to use the Noderr loop for all future development!

The Heart of Noderr: The Four-Step Loop

Every feature you build follows this robust, structured, and verification-driven loop:

┌────────────────────────────────────────────────────────┐
│                    THE NODERR LOOP                     │
│                                                        │
│  You Provide a `PrimaryGoal` (e.g., "Add user login")  │
│                      ↓                                 │
│  [LOOP 1A] Propose Change Set                          │
│       ↓ (Agent analyzes impact, you approve)           │
│  [LOOP 1B] Draft Specs                                 │
│       ↓ (Optional: Spec Verification for large sets)   │
│  [LOOP 2A] Implement Change Set                        │
│       ↓ (Agent builds & runs initial tests)            │
│  [LOOP 2B] Verify Implementation                       │
│       ↓ (Agent audits code vs. spec, reports %)        │
│  [LOOP 3] Finalize & Commit                            │
│       ↓ (Agent updates docs, logs, and commits)        │
│                                                        │
│  ← Return to Start Work Session for the next Goal      │
└────────────────────────────────────────────────────────┘

What Each Step Does:

noderr/prompts/NDv1.9__[LOOP_1A]__Propose_Change_Set.md

  • Agent's Job: Analyzes the PrimaryGoal and identifies every single new or existing node that will be affected.
  • Your Job: Review and approve the proposed Change Set.

noderr/prompts/NDv1.9__[LOOP_1B]__Draft_Specs.md

  • Agent's Job: Marks all nodes as [WIP] and writes detailed specifications.
  • Your Job: Review the specs in the noderr/specs/ directory.
  • Quality Gate: For large Change Sets (≥10 NodeIDs), the AI will recommend running a Spec_Verification_Checkpoint to ensure quality before implementation.

noderr/prompts/NDv1.9__[LOOP_2A]__Implement_Change_Set.md

  • Agent's Job: Writes all code, runs tests, and performs an initial verification against specs.
  • Your Job: Monitor progress, available for any blockers.

noderr/prompts/NDv1.9__[LOOP_2B]__Verify_Implementation.md

  • Agent's Job: Performs a read-only audit comparing the implemented code to the specifications. It reports a factual completion percentage (e.g., "85% complete").
  • Your Job: Decide whether to fix the gaps, accept the work, or modify the specs.

noderr/prompts/NDv1.9__[LOOP_3]__Finalize_And_Commit.md

  • Agent's Job: Updates specs to "as-built" state, logs work, commits.
  • Your Job: Nothing - this step is fully automated.

Your Daily Workflow

Starting Every Work Session

Always begin with:

noderr/prompts/NDv1.9__Start_Work_Session.md

The agent will:

  • Sync with your project state
  • Review recent changes
  • Suggest the next logical task

Building a New Feature (Example with Quality Gates)

This example shows how the new quality gates work with a large feature.

You: noderr/prompts/NDv1.9__Start_Work_Session.md
Agent: "Ready for the next PrimaryGoal."

You: "Primary Goal: Implement a full e-commerce checkout flow"
Agent: [Starts LOOP 1A]
      "This is a large feature affecting 12 NodeIDs. [...] Approve this Change Set?"

You: "I approve"
Agent: [Starts LOOP 1B]
      "...Drafted specs for all 12 NodeIDs. Based on a Change Set size of 12, I recommend we proceed to the Spec Verification Checkpoint."

You: noderr/prompts/NDv1.9__Spec_Verification_Checkpoint.md
Agent: "Specification Verification Checkpoint complete. All specs are present and meet quality standards. Ready to proceed."

You: noderr/prompts/NDv1.9__[LOOP_2A]__Implement_Change_Set.md
Agent: [Implements all 12 nodes...]
      "Implementation and Initial Verification for WorkGroupID [ID] is complete. The Change Set is now ready for the Loop 2B Implementation Completeness Audit."

You: noderr/prompts/NDv1.9__[LOOP_2B]__Verify_Implementation.md
Agent: "Audit complete.
      - Overall Implementation Completion: 80%
      - Fully Implemented: 8/12 nodes
      - Partially Implemented: 2/12 nodes (missing error handling)
      - Not Implemented: 2/12 nodes (payment gateway timeout logic)
      Awaiting Orchestrator decision."

You: "Return to Loop 2 to implement the missing requirements."
Agent: [Returns to implementation to fix gaps...]

Specialized Workflows

Quick Fixes (Micro-Fix)

For tiny changes (typos, small CSS tweaks):

noderr/prompts/NDv1.9__Execute_Micro_Fix.md

Target: UI_LoginForm
Issue: Fix typo in button text "Sigin" -> "Sign in"

Handling Bugs

When something is broken:

noderr/prompts/NDv1.9__Handle_Critical_Issue.md

Affected Component: API_Authentication
Severity: High
Issue Description: Login returns 500 error after 5 failed attempts

Code Cleanup (Refactoring)

To improve existing code:

noderr/prompts/NDv1.9__Refactor_Node.md

Target NodeID: API_UserSearch
Refactoring Goal: Optimize database queries to reduce N+1 problem

Planning Features

Before building, analyze ideas:

noderr/prompts/NDv1.9__Feature_Idea_Breakdown.md

Here are my feature ideas:
- Add social login (Google, GitHub)
- Email notifications
- Dark mode support
- Export data to CSV

Command Reference

Initial Setup

PromptPurposeWhen to Use
noderr/prompts/NDv1.9__Install_And_Reconcile.mdInstall Noderr after initial buildOnce, after extracting ZIP

Core Development Loop

PromptPurposeWhen to Use
noderr/prompts/NDv1.9__Start_Work_Session.mdSync AI with projectBeginning of each session
noderr/prompts/NDv1.9__[LOOP_1A]__Propose_Change_Set.mdAnalyze feature impactAutomatic after PrimaryGoal
noderr/prompts/NDv1.9__[LOOP_1B]__Draft_Specs.mdCreate blueprintsAfter approving Change Set
noderr/prompts/NDv1.9__Spec_Verification_Checkpoint.mdQuality Gate: Verify specs are completeRecommended for Change Sets ≥10 nodes
noderr/prompts/NDv1.9__[LOOP_2A]__Implement_Change_Set.mdBuild and testAfter approving specs (or spec verification)
noderr/prompts/NDv1.9__[LOOP_2B]__Verify_Implementation.mdQuality Gate: Audit implementationAfter Loop 2A is complete
noderr/prompts/NDv1.9__[LOOP_3]__Finalize_And_Commit.mdDocument and commitAfter implementation passes audit

Quick Actions

PromptUse CaseTypical Duration
noderr/prompts/NDv1.9__Execute_Micro_Fix.mdTypos, small tweaks< 5 minutes
noderr/prompts/NDv1.9__Handle_Critical_Issue.mdBugs, broken featuresVaries by severity
noderr/prompts/NDv1.9__Refactor_Node.mdCode quality improvements15-60 minutes

Planning & Analysis

PromptPurposeOutput
noderr/prompts/NDv1.9__Feature_Idea_Breakdown.mdPrioritize multiple featuresMarkdown report in noderr/planning/
noderr/prompts/NDv1.9__Pre_Flight_Feature_Analysis.mdDeep analysis of one featureDetailed implementation plan
noderr/prompts/NDv1.9__Architecture_Health_Review.mdFull project auditHealth score and action items
noderr/prompts/NDv1.9__Advanced_Security_Audit.mdOWASP-based security checkVulnerability report

Troubleshooting

Common Issues and Solutions

"Command not found" or environment errors

Symptoms: AI tries to run commands that don't work

Solutions:

  • Check noderr/environment_context.md was filled out during installation
  • Verify commands work in your terminal
  • Common fixes:
    • Use python3 instead of python
    • Add npx before commands
    • Include virtual environment activation

AI seems confused about project state

Symptoms: AI suggests already-completed tasks or misunderstands architecture

Solutions:

  • Run noderr/prompts/NDv1.9__Start_Work_Session.md to resync
  • Check all NodeIDs in tracker have spec files
  • Verify architecture diagram matches implementation
  • Ensure recent changes were committed

Initial build doesn't match plans

Symptoms: What was built differs significantly from blueprints

Solutions:

  • This is normal! Plans evolve during implementation
  • The Install_And_Reconcile process handles this
  • Review the reconciled files carefully before approving
  • The system documents reality, not ideals

Changes aren't being tracked

Symptoms: Progress percentage wrong, work not showing as verified

Solutions:

  • Follow the complete 4-step Loop
  • Check noderr/noderr_tracker.md shows correct statuses
  • Verify git commits are happening
  • Don't skip steps - each updates different files

Getting Help

When stuck, check these in order:

  1. Review noderr/noderr_log.md - Recent entries often reveal issues
  2. Check noderr/noderr_tracker.md - Ensure dependencies are correct
  3. Verify architecture - Missing connections cause confusion
  4. Test environment commands - Manual testing reveals broken commands
  5. Review recent git commits - See what actually changed

Best Practices for Success

For Initial Setup

  • There's no single "right way" - Use prompts, conversation, or hybrid approaches
  • Take time with your blueprints - Good planning makes everything smoother
  • Start with a simple project - Learn Noderr with something manageable
  • Review reconciliation carefully - This sets the foundation

For Daily Development

  • Always start with a work session - Keeps AI synchronized
  • Trust the process - The loop prevents problems
  • Review specs before implementation - Catches issues early
  • Use planning prompts for complex features - Saves time overall

For Long-term Success

  • Regular health checks - Run Architecture Health Review monthly
  • Address technical debt - Don't let REFACTOR_ tasks pile up
  • Keep environment updated - When tools change, update the file
  • Embrace the commits - Clean history helps debugging

Next Steps

  1. Prepare your three foundational documents
  2. Build your initial prototype
  3. Install Noderr with noderr/prompts/NDv1.9__Install_And_Reconcile.md
  4. Start systematic development!

Remember: The first project might feel slow as you learn the workflow, but each subsequent project becomes faster and more natural. Noderr's true power emerges as projects grow in complexity.

Welcome to systematic, professional AI-powered development. Welcome to Noderr!