# How to Configure Agent Authority and Story-Driven Development Constitution Rules in aios-core

> Master aios-core Agent Authority and Story-Driven Development constitution rules. Learn to edit authority tables and structure story YAML files for seamless integration and development workflows.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Configure Agent Authority by editing the authority table in [`/.aios-core/constitution.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/constitution.md) and declaring matching `exclusive_authority` blocks in agent definitions, while Story-Driven Development requires creating valid story YAML files in `docs/stories/{id}/story.yaml` that pass the constitutional gate in [`dev-develop-story.md`](https://github.com/SynkraAI/aios-core/blob/main/dev-develop-story.md).**

The aios-core framework from SynkraAI enforces a strict constitutional governance model where agents operate under defined authorities and development is strictly story-driven. Understanding how to configure these **Agent Authority and Story-Driven Development constitution rules in aios-core** ensures your AI agents respect exclusive operational boundaries and only execute code against validated stories.

## Where the Constitution Rules Live

The **Synkra AIOS Constitution** serves as the master source of truth for all governance rules. It resides in [[`/.aios-core/constitution.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/constitution.md)](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/constitution.md) and defines two critical principles:

- **Agent Authority** (lines 30-50): Establishes exclusive rights for specific Git operations, versioning, and decision-making
- **Story-Driven Development** (lines 56-68): Mandates that no code may be written without a valid story containing acceptance criteria and tasks

These principles are enforced by **constitutional gates** implemented in specific task files and agent definitions throughout the repository.

## Configuring Agent Authority

### Updating the Constitutional Authority Table

Agent Authority rules are defined in a markdown table within [`constitution.md`](https://github.com/SynkraAI/aios-core/blob/main/constitution.md) (lines 42-50). Each row maps an authority to its exclusive agent(s).

To add a new authority, edit the table:

```markdown
| Autoridade               | Agente Exclusivo |
|--------------------------|------------------|
| git push                 | @devops          |
| PR creation              | @devops          |
| Release/Tag              | @devops          |
| Story creation           | @sm, @po         |
| Architecture decisions   | @architect       |   <!-- NEW -->
| Quality verdicts         | @qa              |

```

Commit this change to [`/.aios-core/constitution.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/constitution.md). The constitutional gate automatically references this table to validate agent permissions.

### Declaring Exclusive Authority in Agent Definitions

Each agent must declare its `exclusive_authority` block in its definition file under [`/.aios-core/development/agents/<agent>.md`](https://github.com/SynkraAI/aios-core/tree/main/.aios-core/development/agents) (e.g., [`architect.md`](https://github.com/SynkraAI/aios-core/blob/main/architect.md), [`devops.md`](https://github.com/SynkraAI/aios-core/blob/main/devops.md)).

For example, in [`/.aios-core/development/agents/architect.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/development/agents/architect.md):

```yaml
exclusive_authority:
  note: 'CRITICAL: This is the ONLY agent authorized to make architecture decisions'
  rationale: 'Centralising architecture prevents conflicting designs'
  enforcement: 'Git hooks + AIOS gate checks'

```

The **UnifiedActivationPipeline** reads this YAML during agent activation and validates the `exclusive_authority` list against the Constitution at runtime.

### Validating Authority with Pre-Push Gates

Run the quality-gate test to confirm new authorities are respected:

```bash
*pre-push   # runs all gates, including Agent Authority validation

```

If a non-authorized agent (e.g., `@dev`) attempts to execute a restricted operation like an architecture decision or git push, the gate aborts with **BLOCK** severity and prevents the action.

## Configuring Story-Driven Development

### Creating Valid Story Files

Story-Driven Development requires every story to exist as a YAML file under `docs/stories/{storyId}/story.yaml`. The constitutional gate in [`/.aios-core/development/tasks/dev-develop-story.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/development/tasks/dev-develop-story.md) validates these fields:

```yaml

# docs/stories/3.14/story.yaml

id: "3.14"
title: "Add GitHub release automation"
status: "Ready"                # must NOT be "Draft"

acceptance_criteria:
  - "Release tag created"
  - "Changelog generated"
tasks:
  - "Implement release script"

```

Required keys include `id` (string), `title` (string), `status` (cannot be `"Draft"`), `acceptance_criteria` (list), and `tasks` (list). Missing any field results in a **BLOCK** status from the gate.

### Understanding the Constitutional Gate

The enforcement mechanism resides in [[`/.aios-core/development/tasks/dev-develop-story.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/development/tasks/dev-develop-story.md)](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/development/tasks/dev-develop-story.md) at lines 92-106 under the **Constitutional Gates** section.

This gate performs four validations:
1. Story file exists at `docs/stories/{storyId}/story.yaml`
2. Status is not `"Draft"`
3. Acceptance criteria are present and non-empty
4. At least one task or sub-task is defined

If any check fails, the gate returns **BLOCK** severity and the `*develop {storyId}` command aborts immediately.

### Running Story Development Tasks

To start development on a story, run:

```bash
*develop 3.14

```

This command triggers the constitutional gate first. Only after the story passes validation (status is "Ready", criteria exist, tasks defined) will the agent proceed with implementation.

To update a story, simply modify the YAML file (e.g., add more acceptance criteria) and commit. The gate always reads the latest file; no additional configuration is required.

## Complete Workflow Example

Here is a complete workflow demonstrating both constitutional rules in action:

```bash

# 1️⃣ Verify story exists and is ready (Story-Driven Development gate)

*develop 3.14

# 2️⃣ Agent authority enforcement during development

#    - @dev writes code

#    - @architect decides on architecture (exclusive authority)

#    - @devops will later push the changes (exclusive git push authority)

# 3️⃣ Pre-push quality gate (includes both constitution checks)

*pre-push                    # runs lint, test, typecheck, CodeRabbit, and Agent Authority gates

# 4️⃣ Push (only @devops can execute)

*push                        # succeeds because the current agent is @devops

```

## Common Pitfalls & How to Fix Them

| Symptom | Cause (Constitution) | Fix |
|---------|----------------------|-----|
| `*develop` aborts with "Story file not found" | Story-Driven Development gate cannot locate `docs/stories/<id>/story.yaml` | Create the YAML file in the correct path and commit |
| `*push` blocked by "Only @devops can git push" | Agent Authority gate detects a non-devops agent attempting a push | Switch to `@devops` (`*activate devops`) or delegate the push to the devops agent |
| Pre-push fails on "CRITICAL CodeRabbit issues" | Quality-First gate (not about authority or story) | Resolve the reported CodeRabbit issues, then rerun `*pre-push` |

## Summary

- The **Synkra AIOS Constitution** in [`/.aios-core/constitution.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/constitution.md) defines **Agent Authority** (lines 30-50) and **Story-Driven Development** (lines 56-68) as non-negotiable principles.
- **Agent Authority** requires updating the constitutional table and declaring `exclusive_authority` blocks in agent definitions under `/.aios-core/development/agents/`.
- **Story-Driven Development** mandates YAML story files in `docs/stories/{id}/story.yaml` with required fields enforced by the gate in [`/.aios-core/development/tasks/dev-develop-story.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/development/tasks/dev-develop-story.md).
- Always run `*pre-push` to validate constitutional compliance before Git operations.

## Frequently Asked Questions

### What happens if an agent tries to execute an action outside its authority?

The **Agent Authority** constitutional gate detects the violation during the `*pre-push` check or when the agent attempts the action, aborting the operation with **BLOCK** severity. According to the implementation in [`/.aios-core/constitution.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/constitution.md) lines 30-50, only agents listed in the authority table may execute their mapped operations.

### Can I disable Story-Driven Development for quick fixes or hotfixes?

No. The **Story-Driven Development** principle defined in [`/.aios-core/constitution.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/constitution.md) lines 56-68 is non-negotiable. The constitutional gate in [`/.aios-core/development/tasks/dev-develop-story.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/development/tasks/dev-develop-story.md) (lines 92-106) will block any `*develop` command if a valid story file does not exist at `docs/stories/{id}/story.yaml` with status not equal to "Draft".

### How do I add a new agent with exclusive authority?

First, add the agent and its authority to the table in [`/.aios-core/constitution.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/constitution.md) (around lines 42-50). Then create or edit the agent definition file at `/.aios-core/development/agents/<agent-name>.md` and include an `exclusive_authority` block with `note`, `rationale`, and `enforcement` fields. Finally, run `*pre-push` to validate the configuration.

### What fields are required in a story YAML file?

According to the constitutional gate implementation in [`/.aios-core/development/tasks/dev-develop-story.md`](https://github.com/SynkraAI/aios-core/blob/main//.aios-core/development/tasks/dev-develop-story.md), a valid story file at `docs/stories/{id}/story.yaml` must include: `id` (string), `title` (string), `status` (must not be "Draft"), `acceptance_criteria` (list), and `tasks` (list). Missing any of these fields results in a **BLOCK** status from the gate.