🌍 About GDA Africa

GDA (Glenhalton Digital Agency) is building the digital infrastructure for Africa's next generation of products and services. NEXUS CLI is GDA's open-source developer framework — the bridge between human intent and AI execution, giving every project a brain that coding agents can link to, learn from, and build upon.

🎯 Why NEXUS?

Scaffolding tools generate files. NEXUS generates understanding.

Every project gets a documentation system AI agents can parse, a knowledge base they learn from, a project brain they check before every task, and a persona that makes them feel like a real teammate — not a generic autocomplete.

✨ Features

🚀 Quick Start

Install

npm install -g @nexus-framework/cli

Create a Project

nexus init my-app

You'll be guided through an interactive setup:

🔮 NEXUS CLI v0.3.0 — AI-Native Development Framework

? What are you building?                › Web Application
? How will your app handle data?        › Cloud First
? Which application patterns?           › PWA, Theming
? Which frontend framework?             › Next.js 15 (App Router)
? Testing framework?                    › Vitest
? Package manager?                      › npm
? Initialize a git repository?          › Yes
? Install dependencies now?             › Yes
? 🎭 What vibe should your AI have?    › 😊 Friendly
? 📏 How detailed should responses be? › ⚖️ Balanced
? 🤖 I'm Nexus! What should I call myself? › Nexus
? ✨ Custom personality note?           › (skip)

✔ Project created successfully!

  cd my-app
  npm run dev

Run It

cd my-app
npm run dev
# → Your app is running at http://localhost:3000

What Happens Next

Open the project in your AI coding tool (Cursor, Copilot, Windsurf, Cline). The AI agent will:

1. Detect the NEXUS instructions automatically (.cursorrules, .github/copilot-instructions.md, etc.)
2. Read index.md — your project brain — to understand status and priorities
3. Scan knowledge.md — the progressive memory — for past decisions and gotchas
4. Check for template docs — if any have status: template, it will auto-populate them by scanning your codebase
5. Start working from the "What's Next" section — no more "what should I build?"

📦 What You Get

Every generated project includes:

The NEXUS Doc System

🧠 Skills System

Skills are pre-read instruction files that tell AI agents how to execute tasks in your specific project — not just what to do, but the exact patterns, conventions, and anti-patterns your codebase follows.

Every project gets a .nexus/skills/ directory with three zones:

.nexus/skills/
  README.md          ← auto-generated index agents read first
  core/              ← framework-matched skills from @nexus-framework/skills
  custom/            ← your own skills (created with nexus skill new, never touched by NEXUS)
  community/         ← skills installed from the registry

Managing Skills

nexus skill list                         # what's installed in this project
nexus skill registry                     # browse everything in the registry
nexus skill registry --framework nextjs  # filter to one framework
nexus skill new                          # scaffold a custom skill interactively
nexus skill status                       # health-check: deprecated, invalid frontmatter
nexus skill install <pkg>                # install a community skill pack
nexus skill remove <name>                # remove a community skill

Custom Skills

nexus skill new my-service-pattern

Guides you through setting a category, trigger phrases, and scaffolds a full markdown template. The AI agent reads this file before any task matching the triggers.

Precedence: custom/ > core/ > community/ — your skills always win.

🎭 Agent Persona

NEXUS lets you configure how AI agents communicate when they're synced with your project.

When an AI agent reads the NEXUS instructions and sees the persona config, it adopts that personality. The user sees "Nexus" in responses — their signal that the agent has read the docs, scanned the knowledge base, and is synced with the project brain.

🏗️ Adopt an Existing Project

Already have a project? Add the NEXUS AI layer without touching your source code.

cd my-existing-app
nexus adopt

This adds .nexus/docs/, .nexus/ai/, and AI tool config files. It does not modify your source code, configs, or dependencies.

After adopting, your AI coding tool will auto-detect the NEXUS docs, scan your codebase to populate them, and ask you about anything it can't infer — giving the AI full project context from that point forward.

📖 Supported Frameworks

🗺️ Roadmap

✅ Shipped

• Core CLI with nexus init, nexus adopt, nexus upgrade, nexus repair
• Interactive prompt system (7 modules including persona)
• Generator engine (8 modules: structure, docs, config, tests, CI/CD, landing page, AI config, skills)
• AI-native documentation system (8 structured files + project brain + knowledge base + onboarding protocol)
• Agent Persona system (tone, verbosity, identity, custom directives)
• Multi-tool AI support (Cursor, Copilot, Windsurf, Cline, Claude Code)
• 6 frontend frameworks supported
• Smart file strategy (upgrade preserves user work, repair fixes corruption)
• Progressive knowledge base (append-only, category-tagged, AI-scannable)
• Skills System — nexus skill (6 subcommands), .nexus/skills/, sourced from @nexus-framework/skills
• nexus pack / nexus unpack — portable .nexus/ migration with zip + verification
• nexus update — self-updating CLI + startup update notifications
• 225 unit tests passing
• Published to npm as @nexus-framework/cli
• CI/CD with auto-publish to npm on version bump

🔜 Next Up (v0.3.x)

• E2E tests — generate a project, run its build, verify all files
• Framework-specific template content (not just landing pages)
• nexus add <feature> — add capabilities to existing NEXUS projects
• Improve error messages and edge case handling

🗓️ Near-term

• Plugin system for custom generators
• Template marketplace / community templates
• Web-based project configurator
• Docker template support
• Strategy pattern generators (PWA service workers, i18n setup, theming engine)

📋 Backlog

• nexus eject — remove NEXUS, keep code
• nexus validate — check project against NEXUS standards
• nexus migrate — migrate from CRA, etc.
• GitLab CI, Bitbucket Pipelines templates
• Pro tier features (paid AI-powered code generation)

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

git clone https://github.com/GDA-Africa/nexus-cli.git
cd nexus-cli && yarn install
yarn lint && yarn test    # 225 tests, zero lint errors