convez.ai
SkillDevOps & InfraestruturaIntermediário
lloydbrian

ASCENT — Framework de Engenharia Opinado

lloydbrian/lloydbriantech-ascent

Do zero a stack rodando em 2min, com disciplina até o dia 1000

Ver no GitHub
BomPluginScore · de 0 a 100

Framework completo que leva um projeto de ideia a stack rodando em menos de dois minutos, mantendo disciplina arquitetônica enquanto cresce. Inclui 28 skills embarcadas, 15 princípios enforçados, ADRs, make vocabulary sectionalizado e protocolos de retomada de sessão para longevidade de projeto.

Instalação

$npx convez-ai lloydbrian/lloydbriantech-ascent

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 2 dias
Versão
v0.4.19
Issues abertas
1
Contribuidores
1

Casos de uso

  • Scaffolding de projetos full-stack com padrões arquitetônicos já aplicados
  • Equipes que precisam de documentação e decisões consistentes ao crescer
  • Desenvolvimento de backends Express + SQLite com observability baseline incluída
  • Implementação de projetos containerizados (Podman/Docker) com práticas DevOps

Veredito

ASCENT é robusto e opinado, resolvendo o problema real de drift arquitetônico em projetos que crescem. A curva de aprendizado é média (15 princípios + vocabulário make + ADRs exigem leitura), mas o investimento se paga rapidamente em consistência e documentação viva. Melhor para equipes que valorizam disciplina estrutural desde o dia 1.

README

A tradução para o português deste README ainda está na fila.

lloydbriantech-ascent

An opinionated engineering framework that takes a project from idea to running stack in under two minutes, then keeps it disciplined as it grows.

Version License Principles Status


Why ASCENT

Most engineering frameworks optimize for Day 0 — the scaffold. ASCENT optimizes for Day 0 through Day 1000: the long arc where projects accumulate decisions, drift from intent, lose documentation freshness, and silently degrade. The framework is built on the observation that most software quality problems are not problems of skill — they are problems of consistency under fatigue, handoff, and time pressure.

ASCENT codifies hard-won patterns — containerization-first development, make-as-operator-vocabulary, ADR discipline, phase-gated delivery, persona-segmented documentation, session resumption — into a framework where every project starts with these properties and keeps them. The framework itself was built using its own principles: 7 ADRs, phase-gated delivery with explicit go-signals, and cluster-based implementation chunks reviewed before merge. See docs/framework/PHILOSOPHY.md for the full rationale.

What you get

A scaffolded ASCENT project ships with all of the following on Day 1:

  • 15 enforced principles — architectural invariants from containerization-first to session resumption (PRINCIPLES.md)
  • 22 reference modules — the knowledge base the parent skill consults at runtime (roles, conventions, protocols)
  • 28 project-embedded skills — ascent-* skills that keep the project honest as it grows (10 implemented, 18 in progress)
  • Working backend + frontend — Express + SQLite-WAL + React + Vite, containerized via Podman/Docker
  • SDLC-sectioned make vocabulary — make help as the single operator entry point, 10 .mk files across META/DEV/TEST/QA/SEC/VALIDATE/DOCS/INFRA sections
  • 7 architectural decision records — container-first, backend layering, make vocabulary, SQLite-WAL, JSON logging, dual licensing, phase-gated delivery
  • Session resumption protocol — session-state.md + working-memory.md so context survives across sessions
  • Working test framework — Vitest for backend unit tests, bash scripts for skill structural tests, make test-all runs everything
  • nginx reverse proxy — three config variants (dev, prod, dist) with security headers and caching
  • Observability baseline — pino JSON logging with W3C TraceContext, structured healthchecks (/healthz + /readyz)

Quick start

Option A — Clone the starter (fastest path to a running stack)

gh repo create lloydbrian/my-new-project \
  --template lloydbrian/lloydbriantech-ascent-starter \
  --private

cd my-new-project

# In Claude Code:
# "Bootstrap this as my-new-project"
# The skill personalizes slugs, applies your option choices, writes .ascent-meta.json

make dev-up
# → http://localhost:3001/healthz responding ✓

Total time from gh repo create to running dev stack: typically under two minutes.

Option B — Skill-only (full customization at scaffold time)

mkdir my-new-project && cd my-new-project

# In Claude Code:
# "Use lloydbriantech-ascent to scaffold this as my-new-project"
# Six-question interview, then full project tree is generated

make dev-up

What the scaffolded project looks like

my-new-project/
├── .ascent-meta.json              # Project identity + current phase
├── .claude/skills/ascent-*/       # 28 project-embedded skills
├── backend/                       # Express + SQLite-WAL + Dockerfile
├── frontend/                      # React + Vite + Dockerfile
├── docker-compose.yml             # Dev stack (bind mounts)
├── nginx/                         # Reverse proxy configs
├── Makefile + make/*.mk           # SDLC-sectioned operator vocabulary
├── docs/architecture/decisions/   # 7 ADRs + INDEX.md
├── docs/delivery/                 # Session state + working memory
└── tests/skills/                  # Skill test scripts

Installing the skill itself

gh repo clone lloydbrian/lloydbriantech-ascent ~/Developer/repositories/lloydbriantech-ascent
cd ~/Developer/repositories/lloydbriantech-ascent
make install
# → Symlinks skills/lloydbriantech-ascent/ into ~/.claude/skills/

Run make uninstall to remove the symlink. make help shows the full operator vocabulary.

How it works

flowchart TD
    A["User intent in Claude Code"] --> B["Parent skill<br/>lloydbriantech-ascent"]
    B --> C{"Routes to 1 of 9 roles"}
    C --> D["delivery-lead"]
    C --> E["architect"]
    C --> F["developer"]
    C --> G["6 more roles"]
    B --> H{"Selects 1 of 3 modes"}
    H --> I["scaffold"]
    H --> J["enhance"]
    H --> K["migrate"]
    I --> L["Scaffolded project"]
    J --> L
    K --> L
    D --> L
    E --> L
    F --> L
    G --> L
    L --> M[".ascent-meta.json"]
    L --> N["28 ascent-* embedded skills"]
    L --> O["15 framework principles"]
    L --> P["Session resumption artifacts"]
    L --> Q["SDLC-sectioned make vocabulary"]
    L --> R["22 reference modules"]

The parent skill lloydbriantech-ascent is a single Claude skill that routes user intent through two axes: role (which engineering concern) and mode (what kind of operation).

Nine roles cover the full project lifecycle: delivery-lead, architect, ui-ux-designer, developer, data-engineer, ai-engineer, tester, devops, and cybersecurity. Each role owns a non-overlapping slice — the architect designs the skeleton, the developer implements features, the devops engineer deploys them. See docs/framework/ARCHITECTURE.md for the full role taxonomy.

Three modes determine the operation type. Scaffold creates a greenfield project (no .ascent-meta.json present). Enhance adds to an existing ASCENT project (.ascent-meta.json present). Migrate brings a non-ASCENT project up to current standards (explicit --migrate flag).

The scaffolded project is self-sustaining: its 28 embedded skills, session resumption protocol, and make vocabulary mean the project can be maintained, audited, and extended without returning to the parent skill.

The 15 principles

Every ASCENT project enforces these invariants. They are not aspirations — they are conditions that must hold. A project that breaks a principle is either broken or has explicitly superseded it via ADR.

#PrincipleWhat it enforces
§1Containerization-firstDev environment is the container; make dev-up from a bare host
§2Make as operator vocabularyOne make target per operation; same name in dev, CI, and runbooks
§3SDLC-sectioned helpmake help groups targets by lifecycle stage (DEV, TEST, QA, ...)
§4Stub-first namingFuture targets ship under their final name from Day 1
§5.env discipline.env never committed; .env.example with empty defaults only
§6Strict backend layeringroutes → controllers → services → storage; only storage writes
§7ADR disciplineEvery constraining decision gets a five-section ADR
§8Phase-gated deliveryNumbered phases, explicit exit criteria, literal go-signal
§9Label-based scopingAll containers, volumes, networks carry the project label
§10Engine compatibility$(ENGINE) auto-detects Podman/Docker; no hardcoded runtime
§11Context-aware executionSkills adapt behavior to current phase and project state
§12Graceful shutdownSIGTERM + configurable grace period; no abrupt kills
§13Dev-status familymake dev-status reports container, database, and endpoint state
§14Persona-segmented docsEvery doc names its audience; 3-click depth limit per persona
§15Session resumptionTransient state and accumulated decisions persist across sessions

Full text with rationale: docs/framework/PRINCIPLES.md

Project-embedded skills

Every scaffolded project ships with 28 project-embedded skills across two tiers: 14 baseline-deep (full decision trees, ~200-250 lines) and 14 specialized-lean (substantive but less exhaustive, ~100-150 lines). All prefixed ascent-*.

Baseline (14 skills, always scaffolded):

SkillPurpose
ascent-self-auditUmbrella audit composing layering, env, and observability checks
ascent-layering-checkValidates backend import graph (routes → controllers → services → storage)
ascent-env-auditValidates .env discipline: gitignored, empty defaults, code-reads match schema
ascent-observability-checkValidates logger, trace context, healthchecks, lifecycle events
ascent-delivery-statusSurfaces current phase, exit-criteria progress, recommended next actions
ascent-feature-intakeDecomposes requests into testable acceptance criteria
ascent-standupSummarizes recent activity into standup format
ascent-adr-writeGuides ADR creation with interview, numbering, INDEX.md update
ascent-doc-stubGenerates persona-targeted documentation skeletons
ascent-make-targetProposes correctly-named make targets with section-aware placement
ascent-reflectCaptures end-of-session state and decisions
ascent-handoffDocuments project state for another developer
ascent-onboardGuides a new developer through the project
ascent-healthAggregates health signals across all health-check skills

Specialized and conditional (14 skills):

ascent-data-health · ascent-doc-sweep · ascent-dependency-health · ascent-adr-conformance · ascent-skills-doctor · ascent-qa · ascent-release-readiness · ascent-security-audit · ascent-sec-posture · ascent-cost-posture · ascent-vitality · ascent-ai-evals · ascent-design-system-audit · ascent-persona-coverage

Implementation status: All 28 skills implemented across 8 clusters per docs/framework/PHASE-3-PLAN.md. Each cluster shipped as a reviewed PR with behavior-verifying test scripts. 14 baseline-deep skills (~200-250 lines each) and 14 specialized-lean skills (~100-150 lines each).

Session resumption

Principle §15 treats session resumption as a first-class engineering concern. Two artifacts persist context across sessions:

  • docs/delivery/session-state.md — transient working state (current focus, next actions, blockers). Gitignored. Captured via make session-snapshot, restored via make session-resume.
  • docs/delivery/working-memory.md — accumulated decisions, patterns adopted, patterns rejected. Git-tracked. Grows over the project's lifetime.

Skills classify these files using a four-state model (MISSING / EMPTY / STALE / FRESH) and adapt their behavior accordingly. See skills/lloydbriantech-ascent/references/session-protocol.md for the full protocol.

Documentation by persona

ASCENT documentation is segmented by reader. The canonical persona→entry-point mapping lives in skills/lloydbriantech-ascent/references/audience-mapping.md. Brief summary:

PersonaNeedsEntry point
ArchitectMental model, decisions, rationaleARCHITECTURE.md → DECISIONS/INDEX.md
DeveloperBackend layering, observability hooks, test conventionsPHILOSOPHY.md → role-developer.md
OperatorMake-target catalog, runbooks, healthcheck semanticsmake help (lands per scaffolded project)
ContributorPR conventions, commit format, ADR template, contribution barCONTRIBUTING.md
LearnerWhy ASCENT, what it provides, where it's headingPHILOSOPHY.md → ROADMAP.md

See audience-mapping.md for full per-persona detail — what each doesn't need, path-depth bounds, and how to add new personas.

Documentation map

If you want to...Read
Understand the framework's design rationaledocs/framework/PHILOSOPHY.md
See the architectural invariants enumerateddocs/framework/PRINCIPLES.md
Know what ASCENT is and isn't fordocs/framework/SCOPE.md
See where the framework is headingdocs/framework/ROADMAP.md
Understand the framework's own architecturedocs/framework/ARCHITECTURE.md
Read the framework's architectural decisionsdocs/framework/DECISIONS/INDEX.md
See the Phase 3 skill implementation plandocs/framework/PHASE-3-PLAN.md
Contribute to the frameworkCONTRIBUTING.md
See what changed between versionsCHANGELOG.md

Status and roadmap

ASCENT has shipped 5 releases across 4 completed phases:

PhaseVersionDateWhat shipped
Phase 0 — Foundationv0.1.0-alphaMay 14, 2026Repo identity, 7 ADRs, framework docs
Phase 1 — Parent skillv0.2.0May 15, 2026SKILL.md with routing logic, 22 reference modules, Makefile tree
Phase 2 — Template assetsv0.3.0May 16, 2026Full scaffolded project template, 14-step smoke test
v0.3.1 — Session resumptionv0.3.1May 17, 2026Principle §15, session-protocol.md, make session-snapshot/resume
Phase 3 — Skillsv0.4.0May 20, 202628 project-embedded skills, 28 test scripts, 4 architectural patterns

Currently: Phase 3 complete. Phase 4 — Scaffolding scripts — awaiting signal.

Next: Phase 4 — Scaffolding scripts (the skill actually writes files). Phase 5 — Test harness with evals. Phase 6 — Starter repo generation. Phase 7 — First production project.

See docs/framework/ROADMAP.md for exit criteria per phase.

Who should use this

Use ASCENT if:

  • You want a project that starts with production-grade conventions on Day 1 (not retrofitted later)
  • You value explicit architectural decisions over implicit ones
  • You work with Claude Code and want the AI to understand your project's engineering standards
  • You want a framework that enforces consistency across session boundaries, developer handoffs, and time pressure

Don't use ASCENT if:

  • You need a mature, stable framework today — ASCENT is pre-v1.0 and actively evolving
  • Your project doesn't use containers (§1 is non-negotiable)
  • You want maximum flexibility with minimum opinion — ASCENT is deliberately opinionated
  • Your stack is fundamentally different from the baseline (Express + React + SQLite-WAL) and you're not willing to write a migration path

Contributing

ASCENT is currently a single-author framework (Lloyd D., lloydbriantech). Contributions, suggestions, and bug reports are welcome via GitHub issues. See CONTRIBUTING.md for the contribution model, versioning approach, and review bar.

Phase 3 established a cluster-based PR discipline: each cluster of related skills ships as a single reviewed PR with behavior-verifying test scripts, full validator passes, and a review packet before merge. This discipline carries forward for future contributions.

Support

ASCENT is free and open-source under the MIT/Apache-2.0 dual license. If the framework has saved you time on a project, support is appreciated but never expected:

☕ buymeacoffee.com/lloydbriantech

License

Dual-licensed under either of:

at your option. See LICENSE for the formal statement.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you shall be dual-licensed as above, without any additional terms or conditions.


ASCENT is a lloydbriantech engineering framework. Built with discipline, in the open.

Ver o original no GitHub

Bom para

Relacionados