Skip to content

Commit 1ac4940

Browse files
AndrewWestbergAndrewWestberg
committed
chore: update dependencies and client timeouts
1 parent 105e98b commit 1ac4940

File tree

29 files changed

+1293
-39
lines changed

29 files changed

+1293
-39
lines changed

‎.agent/SOPs/readme.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# 📝 Standard Operating Procedures (SOPs)
2+
3+
> **Learn from experience. Document solutions. Prevent repeated mistakes.**
4+
5+
This folder contains Standard Operating Procedures — step-by-step guides for tasks that have been successfully completed or issues that have been resolved.
6+
7+
---
8+
9+
## Purpose
10+
11+
When the agent (or you) solves a complex problem or successfully integrates a service:
12+
13+
1. **Document the solution** — Create an SOP immediately
14+
2. **Include pitfalls** — Note what went wrong and how it was fixed
15+
3. **Make it reusable** — Future work on similar tasks should reference this
16+
17+
---
18+
19+
## How to Create a New SOP
20+
21+
Ask the agent:
22+
23+
> "Generate SOP for [task/integration name]"
24+
25+
Or manually create using the template below.
26+
27+
---
28+
29+
## SOP Template
30+
31+
```markdown
32+
# SOP: [Task/Integration Name]
33+
34+
## Overview
35+
Brief description of what this SOP covers.
36+
37+
## Prerequisites
38+
- List of required tools, access, or knowledge
39+
- Environment setup needed
40+
41+
## Step-by-Step Procedure
42+
43+
### Step 1: [Step Title]
44+
Description of what to do.
45+
46+
```bash
47+
# Commands if applicable
48+
example command
49+
```
50+
51+
### Step 2: [Step Title]
52+
Continue with next steps...
53+
54+
## Common Pitfalls
55+
56+
### ⚠️ [Pitfall Name]
57+
**Problem:** What goes wrong
58+
**Solution:** How to fix it
59+
60+
### ⚠️ [Another Pitfall]
61+
**Problem:** What goes wrong
62+
**Solution:** How to fix it
63+
64+
## Verification
65+
How to confirm the task was successful.
66+
67+
## References
68+
- Link to relevant documentation
69+
- Related code files
70+
71+
---
72+
73+
**Created:** YYYY-MM-DD
74+
**Last Updated:** YYYY-MM-DD
75+
**Author:** [Name/Agent]
76+
```
77+
78+
---
79+
80+
## SOP Categories
81+
82+
Organize SOPs by category:
83+
84+
```
85+
.agent/SOPs/
86+
├── readme.md (this file)
87+
├── integration/
88+
│ └── ogmios-connection.md
89+
├── release/
90+
│ └── maven-publish.md
91+
└── debugging/
92+
└── websocket-timeouts.md
93+
```
94+
95+
---
96+
97+
## Index of SOPs
98+
99+
> Update this section as new SOPs are added.
100+
101+
| Category | SOP Name | Description | Date |
102+
|----------|----------|-------------|------|
103+
104+
---
105+
106+
## When to Create an SOP
107+
108+
Create an SOP when:
109+
110+
- ✅ A complex integration is successfully completed
111+
- ✅ A tricky bug is finally resolved
112+
- ✅ A deployment issue is troubleshot
113+
- ✅ A new service or tool is set up for the first time
114+
- ✅ The same question/issue comes up multiple times
115+
116+
---
117+
118+
## Best Practices
119+
120+
1. **Be specific** — Include exact commands, file paths, and configuration
121+
2. **Include context** — Explain *why* steps are necessary, not just *what*
122+
3. **Test the SOP** — Verify steps work by following them yourself
123+
4. **Keep updated** — Revise when processes change
124+
5. **Link related SOPs** — Cross-reference when tasks are related

‎.agent/readme.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# 📚 Kogmios Agent Documentation Index
2+
3+
> **For AI Agents:** Read this file first to understand available documentation and when to reference each resource.
4+
5+
This folder contains documentation for assisting with development on the Kogmios project (Kotlin implementation of an Ogmios client). Use this index to quickly navigate to the relevant documentation for your current task.
6+
7+
---
8+
9+
## 🗺️ Quick Navigation
10+
11+
| Folder | Purpose | When to Read |
12+
|--------|---------|--------------|
13+
| [`/system`](./system/) | Architecture, build/publish, design patterns | **First**, for any architectural decisions or understanding system design |
14+
| [`/task`](./task/) | PRDs and implementation plans history | When implementing new features similar to past work |
15+
| [`/SOPs`](./SOPs/) | Standard Operating Procedures | When encountering known issues or following established patterns |
16+
| [`/workflows`](./workflows/) | Step-by-step development workflows | When executing specific development tasks |
17+
18+
---
19+
20+
## 📁 Folder Details
21+
22+
### `/system` — Architecture & Patterns
23+
24+
**The source of truth for major architectural decisions.**
25+
26+
Read these files to understand:
27+
- Overall system architecture and component relationships
28+
- Client/protocol layout and data models
29+
- Build, publish, and versioning expectations
30+
- Integration patterns with Ogmios/Cardano
31+
32+
Files:
33+
- `architecture.md` — System overview, modules, protocols, data flow
34+
35+
---
36+
37+
### `/task` — Implementation History
38+
39+
**Successful PRDs and implementation plans for reference.**
40+
41+
Before implementing a feature:
42+
1. Check if a similar feature was implemented before
43+
2. Use past plans as templates for consistency
44+
3. Follow established patterns from successful implementations
45+
46+
This folder uses subdirectories per major feature/task.
47+
48+
---
49+
50+
### `/SOPs` — Standard Operating Procedures
51+
52+
**Learnings from resolved issues and best practices.**
53+
54+
When an issue is resolved or a complex integration succeeds:
55+
1. Document the step-by-step solution
56+
2. Include common pitfalls and how to avoid them
57+
3. Reference related code or configuration
58+
59+
**To create a new SOP**, ask the agent:
60+
> "Generate SOP for [task/integration name]"
61+
62+
---
63+
64+
### `/workflows` — Development Workflows
65+
66+
**Step-by-step guides for common development tasks.**
67+
68+
Available workflows:
69+
70+
| Workflow | Description | Trigger |
71+
|----------|-------------|---------|
72+
| [`build.md`](./workflows/build.md) | Build project | `/build` |
73+
| [`test.md`](./workflows/test.md) | Run tests | `/test` |
74+
| [`backend_dependencies.md`](./workflows/backend_dependencies.md) | Check dependency updates | `/backend_dependencies` |
75+
| [`update-doc.md`](./workflows/update-doc.md) | Update documentation | `/update-doc` |
76+
77+
---
78+
79+
## 🏗️ Project Overview
80+
81+
**Kogmios** is a Kotlin client implementation for the Ogmios WebSocket interface. It wraps Ogmios JSON-WSP messages into typed models and uses coroutines for async operations.
82+
83+
### Technology Stack
84+
85+
| Layer | Technology | Notes |
86+
|-------|------------|-------|
87+
| **Language** | Kotlin 2.x on Java 21 | Kotlin JVM library |
88+
| **Networking** | Ktor client (CIO + websockets) | WebSocket communication |
89+
| **Serialization** | kotlinx-serialization | JSON-WSP payloads |
90+
| **Concurrency** | Kotlin coroutines | Suspended client calls |
91+
| **Logging** | Logback, Commons Logging | Client logging |
92+
| **Build** | Gradle (Kotlin DSL) | Single module |
93+
94+
### Module Overview
95+
96+
```
97+
kogmios
98+
└── src/
99+
├── main/kotlin/io/newm/kogmios/...
100+
└── test/kotlin/io/newm/kogmios/...
101+
```
102+
103+
### Client Types
104+
105+
Kogmios exposes four logical clients:
106+
- `StateQuery`
107+
- `TxSubmit`
108+
- `TxMonitor`
109+
- `ChainSync`
110+
111+
---
112+
113+
## ⚡ Quick Commands
114+
115+
### Build & Test
116+
```bash
117+
# Build
118+
./gradlew build
119+
120+
# Run tests
121+
./gradlew test
122+
```
123+
124+
### Code Quality
125+
```bash
126+
# Lint check
127+
./gradlew ktlintCheck
128+
129+
# Auto-fix formatting
130+
./gradlew ktlintFormat
131+
```
132+
133+
---
134+
135+
## 🧩 Skills
136+
137+
**Skills are reusable instructions the agent can load with the `skill` tool.**
138+
139+
Current status:
140+
- `git-commit-formatter` — Formats git commit messages to Conventional Commits when asked to commit or draft commit messages. See `.agent/skills/git-commit-formatter/SKILL.md`.
141+
142+
If skills are added, list them here with a short description and usage guidance.
143+
144+
## 🔐 Security Notes
145+
146+
- Never commit secrets or API keys
147+
- Avoid checking in credentials for Ogmios nodes

‎.agent/skills/git-commit-formatter/SKILL.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
name: git-commit-formatter
3+
description: Formats git commit messages according to Conventional Commits specification. Use this when the user asks to commit changes or write a commit message.
4+
---
5+
6+
# Git Commit Formatter Skill
7+
8+
When writing a git commit message, you MUST follow the Conventional Commits specification.
9+
10+
## Format
11+
`<type>[optional scope]: <description>`
12+
13+
## Allowed Types
14+
- **feat**: A new feature
15+
- **fix**: A bug fix
16+
- **docs**: Documentation only changes
17+
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, etc)
18+
- **refactor**: A code change that neither fixes a bug nor adds a feature
19+
- **perf**: A code change that improves performance
20+
- **test**: Adding missing tests or correcting existing tests
21+
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation
22+
23+
## Instructions
24+
1. Analyze the changes to determine the primary `type`.
25+
2. Identify the `scope` if applicable (e.g., specific component or file).
26+
3. Write a concise `description` in imperative mood (e.g., "add feature" not "added feature").
27+
4. If there are breaking changes, add a footer starting with `BREAKING CHANGE:`.
28+
29+
## Example
30+
`feat(auth): implement login with google`

0 commit comments

Comments
 (0)