Three-layer CLI command structure: optimized for AI pattern recognition

[deepracticexs]

Background

NodeSpec is designed as an AI-first tool. Our CLI command structure should prioritize AI's pattern recognition capabilities over human memorization convenience.

Design Decision: Three-layer Structure

nodespec [role] [domain] [action] [args]

Example:

nodespec scaffold monorepo init [name]
nodespec scaffold package add <name>
nodespec scaffold app add <name>
nodespec scaffold config init

Why Three Layers (vs Flat Action)

Alternative Considered: Flat Action (Rejected)

nodespec scaffold [action] [args]
nodespec scaffold init-monorepo [name]
nodespec scaffold add-package <name>
nodespec scaffold add-app <name>

Comparison

Aspect	Three-layer (domain + action)	Flat action (verb-domain)
Pattern Inference	✅ Cartesian product: {domain} × {action}	❌ Linear: only same-verb patterns
Learning Cost	✅ 3 domains + 5 actions = 8 concepts → 15 commands	❌ 15 composite actions = 15 concepts
Add New Domain	✅ Auto inherits all actions	❌ Must define N new composite commands
Add New Action	✅ Auto applies to all domains	❌ Must define M new composite commands
Command Length	⚠️ Longer (not a problem for AI)	✅ Shorter (but loses composability)

AI Pattern Recognition Advantages

1. Combinatorial Reasoning:

   • Given: scaffold package add
   • AI infers: scaffold {package|app|service} {add|remove|list}
   • Clear combination space

2. Low Learning Cost:

   • Learn: 3 domains + 5 actions = 8 concepts
   • Generate: 3 × 5 = 15 valid commands
   • High knowledge compression ratio

3. Extensibility:

   # Add new domain "plugin" → all actions available
   nodespec scaffold plugin add <name>
   nodespec scaffold plugin remove <name>
   nodespec scaffold plugin list
   
   # Add new action "validate" → applies to all domains  
   nodespec scaffold package validate
   nodespec scaffold app validate
   nodespec scaffold config validate

4. Semantic Clarity:

   • Think: "I want to operate on {domain}, perform {action}"
   • Matches human reasoning and AI prompting

Implementation Structure

commands/
├── scaffold/
│   ├── index.ts              # scaffold role
│   ├── monorepo/
│   │   ├── init.ts           # action
│   │   └── create.ts         # action
│   ├── package/
│   │   ├── add.ts
│   │   ├── remove.ts
│   │   └── list.ts
│   ├── app/
│   │   ├── add.ts
│   │   ├── remove.ts
│   │   └── list.ts
│   └── config/
│       ├── init.ts
│       └── update.ts

Pattern Template

For AI to generate commands:

Role: {scaffold, architect, product, test, ...}
Domain: {monorepo, package, app, service, config, ...}
Action: {init, create, add, remove, list, update, validate, ...}

Template: nodespec <role> <domain> <action> [args]

Human Convenience (Optional)

While optimizing for AI, we can still provide aliases for humans:

# Alias (optional)
nodespec init → nodespec scaffold monorepo init
nodespec add package <name> → nodespec scaffold package add <name>

Internal: three-layer structure
External: optional shortcuts

Decision Rationale

Primary contradiction: Simplicity vs Composability

• For humans: Shorter commands are easier to remember
• For AI: Structured patterns are easier to infer

Resolution: Optimize for AI's strengths (pattern recognition), not human weaknesses (memory)

This is a "design for AI, not for humans" decision, aligning with NodeSpec's vision of making Node.js development AI-native.

Related

• Issue Redesign CLI command structure: from concept-based to role-based domains #10: Redesign CLI from concept-based to role-based
• Philosophy: AI-first tool design
• Architecture: PATEOAS - domain → action hyperlink structure

[deepracticexs]

✅ Final CLI Design: Four-Layer Structure

After thorough analysis combining AI-first principles and BDD best practices, we've finalized the CLI structure:

nodespec [role] [domain] [action] [object] [...args]

Four-Layer Semantics

[role] - Responsibility/Role

• Who is performing this task
• Value: Responsibility boundaries, context compression for AI

[domain] - Workspace Domain

• Which workspace to operate in (implies directory structure)
• Value: Clear scope, maps to physical directories

[action] - Operation

• What operation to perform
• Value: Clear intent (verb)

[object] - Target Object

• On what to perform the operation (specific instance)
• Value: Target entity, dynamic parameter

Role Definitions

Role: dev (Developer)

# Domain: monorepo (workspace = project root)
nodespec dev monorepo init [project-name]
nodespec dev monorepo validate

# Domain: app (workspace = apps/)
nodespec dev app add my-cli
nodespec dev app list
nodespec dev app remove my-cli

# Domain: service (workspace = services/)
nodespec dev service add api-gateway
nodespec dev service list

# Domain: package (workspace = packages/)
nodespec dev package add core-lib
nodespec dev package list

# Domain: config (workspace = root config files)
nodespec dev config init
nodespec dev config validate

Role: pm (Product Manager)

# Domain: feature (workspace = packages/[pkg]/features/)
nodespec pm feature add my-cli auth
nodespec pm feature list my-cli
nodespec pm feature remove my-cli auth
nodespec pm feature validate my-cli

Role: qa (QA Engineer)

# Domain: test (workspace = packages/[pkg]/tests/)
nodespec qa test run my-cli
nodespec qa test run my-cli --feature auth
nodespec qa test watch my-cli
nodespec qa test report my-cli

# Domain: step (workspace = packages/[pkg]/tests/steps/)
nodespec qa step generate my-cli auth
nodespec qa step list my-cli
nodespec qa step validate my-cli

Role: ops (DevOps)

# Domain: docker
nodespec ops docker build my-cli
nodespec ops docker run my-cli

# Domain: deploy
nodespec ops deploy start my-service prod
nodespec ops deploy stop my-service prod

Domain to Directory Mapping

Role	Domain	Physical Directory	Object Scope
dev	monorepo	./	project name
dev	app	apps/	app name
dev	service	services/	service name
dev	package	packages/	package name
dev	config	./ (config files)	config type
pm	feature	packages/[pkg]/features/	package name
qa	test	packages/[pkg]/tests/	package name
qa	step	packages/[pkg]/tests/steps/	package name
ops	docker	container space	app/service name
ops	deploy	deployment env	service name

Feature File Structure

apps/cli/features/
├── dev/                     # Role
│   ├── monorepo/            # Domain
│   │   ├── init/            # Action
│   │   │   └── init.feature
│   │   └── validate/
│   │       └── validate.feature
│   ├── app/
│   │   ├── add/
│   │   │   └── add.feature
│   │   ├── list/
│   │   │   └── list.feature
│   │   └── remove/
│   │       └── remove.feature
│   ├── service/
│   ├── package/
│   └── config/
├── pm/                      # Role
│   └── feature/             # Domain
│       ├── add/
│       │   └── add.feature
│       ├── list/
│       │   └── list.feature
│       └── validate/
│           └── validate.feature
├── qa/                      # Role
│   ├── test/
│   │   ├── run/
│   │   │   └── run.feature
│   │   └── watch/
│   │       └── watch.feature
│   └── step/
│       ├── generate/
│       │   └── generate.feature
│       └── list/
│           └── list.feature
└── ops/                     # Role
    ├── docker/
    │   └── build/
    │       └── build.feature
    └── deploy/
        └── start/
            └── start.feature

Why This Design Works for AI

1. Four Independent Semantic Layers: Each layer provides distinct context
2. Inferrable Structure: AI can reason about the command structure
3. Clear Directory Mapping: Domain maps directly to physical directories
4. Role-Based Context Compression: Role implicitly defines available domains and responsibilities

Migration Path

Current scaffold commands map to new structure:

# Old
nodespec scaffold monorepo init
nodespec scaffold app add my-cli

# New  
nodespec dev monorepo init
nodespec dev app add my-cli

Next Steps

1. Implement dev role with existing scaffold domains
2. Implement pm role for feature management
3. Implement qa role for test management
4. Document role-domain-action-object pattern