Skip to content

feat(web): add agent-friendly CLI design section (#28) #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
crrow merged 1 commit into from
Mar 26, 2026
Merged

feat(web): add agent-friendly CLI design section (#28) #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 68 additions & 7 deletions web/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,11 +80,11 @@ <h3 class="card__title">CI/CD Ready</h3>
</p>
</div>
<div class="card reveal">
<span class="card__icon">&#x1F9E0;</span>
<h3 class="card__title">Claude Code Skills</h3>
<span class="card__icon">&#x1F916;</span>
<h3 class="card__title">Agent-Friendly</h3>
<p class="card__desc">
Built-in skills teach Claude Code your project conventions.
Autonomous /dev pipeline from design to shipping.
JSON stdout, actionable errors, example-driven help &mdash;
designed for AI agents to operate reliably.
</p>
</div>
<div class="card reveal">
Expand All @@ -99,6 +99,67 @@ <h3 class="card__title">Release Automation</h3>
</div>
</section>

<!-- Agent-Friendly Design -->
<section class="agent-design" aria-labelledby="agent-heading">
<div class="container">
<h2 id="agent-heading" class="section-title reveal">Built for AI Agents</h2>
<p class="agent-design__intro reveal">
AI agents operate your CLI programmatically. This template bakes in the
<a href="https://github.com/rararulab/.github/blob/main/docs/agent-friendly-cli.md" class="agent-design__link">rararulab agent-friendly CLI standards</a>
so every generated project is agent-ready from day one.
</p>
<div class="principles">
<div class="principle reveal">
<span class="principle__number">01</span>
<h3 class="principle__title">JSON stdout, logs stderr</h3>
<p class="principle__desc">Structured output on stdout for machine parsing. Human-readable logs on stderr. Never mix formats.</p>
</div>
<div class="principle reveal">
<span class="principle__number">02</span>
<h3 class="principle__title">Fail fast with suggestions</h3>
<p class="principle__desc">Every error includes a <code>suggestion</code> field so agents can self-correct without human intervention.</p>
</div>
<div class="principle reveal">
<span class="principle__number">03</span>
<h3 class="principle__title">Non-interactive first</h3>
<p class="principle__desc">Every parameter passable via flags. No stdin prompts without a flag equivalent. Agents cannot handle dynamic prompts.</p>
</div>
<div class="principle reveal">
<span class="principle__number">04</span>
<h3 class="principle__title">Example-driven help</h3>
<p class="principle__desc">Every subcommand's <code>--help</code> includes runnable examples. Agents pattern-match better than they parse prose.</p>
</div>
<div class="principle reveal">
<span class="principle__number">05</span>
<h3 class="principle__title">Idempotent operations</h3>
<p class="principle__desc">Agents retry frequently. Create operations return success if the resource already exists &mdash; no duplicate side effects.</p>
</div>
<div class="principle reveal">
<span class="principle__number">06</span>
<h3 class="principle__title">Dry-run &amp; force bypass</h3>
<p class="principle__desc">Destructive commands support <code>--dry-run</code>. Interactive confirmations have <code>--yes</code> to bypass. Safe automation by default.</p>
</div>
</div>

<div class="agent-design__terminal reveal">
<div class="terminal">
<div class="terminal__bar">
<span class="terminal__dot"></span>
<span class="terminal__dot"></span>
<span class="terminal__dot"></span>
</div>
<pre class="terminal__body" aria-label="Agent-friendly JSON output"><code><span class="terminal__comment"># Success: structured JSON on stdout</span>
<span class="terminal__prompt">$</span> my-cli deploy --env staging
<span class="terminal__json">{"ok": true, "action": "deploy", "deploy_id": "d-123"}</span>

<span class="terminal__comment"># Error: actionable suggestion included</span>
<span class="terminal__prompt">$</span> my-cli deploy
<span class="terminal__json-err">{"ok": false, "error": "missing --env", "suggestion": "add --env staging or --env prod"}</span></code></pre>
</div>
</div>
</div>
</section>

<!-- Install / Quickstart -->
<section class="install" aria-labelledby="install-heading">
<div class="container">
Expand Down Expand Up @@ -127,9 +188,9 @@ <h3 class="install__method-title reveal">Create Your Own</h3>
</div>

<ol class="steps reveal">
<li>Install instantly via <code>npx</code> — no Rust required</li>
<li>Or generate your own project from the template</li>
<li>Claude Code skills guide your development workflow</li>
<li>Install instantly via <code>npx</code> &mdash; no Rust required</li>
<li>Or generate your own project with <code>cargo generate</code></li>
<li>Agent-friendly by default &mdash; JSON output, actionable errors</li>
</ol>
</div>
</section>
Expand Down
87 changes: 87 additions & 0 deletions web/src/style.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,93 @@ html.js .features__grid .reveal:nth-child(6) { transition-delay: 400ms; }
line-height: 1.7;
}

/* ===== Agent-Friendly Design ===== */
.agent-design {
padding: var(--sp-20) 0;
background: var(--color-surface);
}

.agent-design__intro {
max-width: 640px;
margin: 0 auto var(--sp-12);
text-align: center;
font-size: var(--text-lg);
color: var(--color-muted);
line-height: 1.7;
}

.agent-design__link {
color: var(--color-pop);
text-decoration: underline;
text-underline-offset: 2px;
transition: color var(--motion-fast);
}

.agent-design__link:hover {
color: var(--color-pop-hover);
}

.principles {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
gap: var(--sp-6);
margin-bottom: var(--sp-12);
}

.principle {
padding: var(--sp-6);
border-left: 3px solid var(--color-pop);
background: var(--color-bg);
border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
}

.principle__number {
display: inline-block;
font-family: var(--font-mono);
font-size: var(--text-sm);
font-weight: 500;
color: var(--color-pop);
margin-bottom: var(--sp-2);
}

.principle__title {
font-size: var(--text-base);
font-weight: 700;
margin-bottom: var(--sp-2);
}

.principle__desc {
color: var(--color-muted);
font-size: var(--text-sm);
line-height: 1.7;
}

.agent-design__terminal {
max-width: 640px;
margin: 0 auto;
}

.terminal__comment {
color: var(--color-muted);
font-style: italic;
}

.terminal__json {
color: var(--color-ok);
}

.terminal__json-err {
color: var(--color-pop);
}

/* Stagger for principles */
html.js .principles .reveal:nth-child(1) { transition-delay: 0ms; }
html.js .principles .reveal:nth-child(2) { transition-delay: 80ms; }
html.js .principles .reveal:nth-child(3) { transition-delay: 160ms; }
html.js .principles .reveal:nth-child(4) { transition-delay: 240ms; }
html.js .principles .reveal:nth-child(5) { transition-delay: 320ms; }
html.js .principles .reveal:nth-child(6) { transition-delay: 400ms; }

/* ===== Install / Quickstart ===== */
.install {
padding: var(--sp-20) 0;
Expand Down
Loading